Step 5: Build multi-tenant interaction recording authorized using activity data authorization (ADA)

Introduction

As discussed in the requirements step, keeping a record of interactions with customers is the most important function of a CRM system. In this step we’re going to build APIs to let users of our system record and manage past and future interactions with their customers and prospects.

Apart from building the CRUD operations, we need to also make sure that each user can only access and modify interactions for contacts that belongs to him. As we saw in the previous step about building contact management, ASK’s Activity-Data Authorization (ADA) will help us in applying this access-control automatically often without needing to write any line of authorization logic.

Interaction service model

Following the same approach, we also define the Interaction service model:

(Add the following code as Interaction.cs into the folder Models.)

using System;
using System.ComponentModel.DataAnnotations;
using SuperCRM.DataModels;

namespace SuperCRM.Models
{
	public class Interaction
	{
		public Guid? Id { get; set; }

		[Required]
		public Guid? ContactId { get; set; }

		public InteractionMethod Method { get; set; }

		[MaxLength(256)]
		public string MethodDetails { get; set; }

		public string Notes { get; set; }

		public DateTime InteractionDate { get; set; }

		public DateTime CreatedDate { get; set; }

		public string CreatedByName { get; set; }
	}

	public class GetInteractions : PagingModel
	{
		public Guid? ContactId { get; set; }
	}
}

Automapper mapping

Define mappings for interaction models in the mapping profile:

public WebAppProfile()
{
	...
	CreateMap<DbInteraction, Interaction>()
		.ForMember(d => d.CreatedByName, o => o.MapFrom(s => s.CreatedBy.Name));

	CreateMap<Interaction, DbInteraction>()
		.ForMember(d => d.Id, o =>
		{
			o.PreCondition((s, d, rc) => d.Id == Guid.Empty);
			o.MapFrom(s => Guid.NewGuid());
		})
		.ForMember(d => d.CreatedById, o => o.Ignore())
		.ForMember(d => d.CreatedDate, o =>
		{
			o.PreCondition((s, d, rc) => d.CreatedDate == DateTime.MinValue);
			o.MapFrom(s => DateTime.UtcNow);
		});
}

For the mapping from service model to data entity, we’re ignoring properties such as CreatedById – these will be initialized by the server from the CurrentUser. Both Id and CreatedDate are also not accepting input from user – instead are being initialized in the mapping itself, but only when the destination has no value – which means that a new entity is being created, as otherwise these properties are read-only during updates.

Interaction CRUD operations

Add the following code as InteractionController.cs into the folder Controllers:

using ASPSecurityKit;
using ASPSecurityKit.Net;
using AutoMapper;
using AutoMapper.QueryableExtensions;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using SuperCRM.DataModels;
using SuperCRM.ModelBinding;
using SuperCRM.Models;
using System;
using System.Linq;
using System.Linq.Expressions;
using System.Threading.Tasks;

namespace SuperCRM.Controllers
{
    [Route("interactions")]
    [Route("contacts/{ContactId}/interactions")]
    public class InteractionController : SiteControllerBase
    {
        private readonly AppDbContext dbContext;
        private readonly IMapper mapper;

        public InteractionController(IUserService<Guid, Guid, DbUser> userService,
	        INetSecuritySettings securitySettings, ISecurityUtility securityUtility, IConfig config, AppDbContext dbContext, IMapper mapper) : base(userService,
	        securitySettings, securityUtility, config)
        {
	        this.dbContext = dbContext;
	        this.mapper = mapper;
        }

        [HttpGet]
        [PossessesPermissionCode, AuthPermission]
        public async Task<BaseListResponse<Interaction>> GetInteractions([FromQuery] GetInteractions model)
        {
            Expression<Func<DbInteraction, bool>> predicate;
            if (model.ContactId.HasValue)
                predicate = i => i.ContactId == model.ContactId.Value;
            else
                predicate = i => i.Contact.OwnerId == this.UserService.CurrentUser.OwnerUserId;

            var result = new
            {
	            Total = await this.dbContext.Interactions.CountAsync(predicate),
	            ThisPage = await this.dbContext.Interactions.Where(predicate)
		            .OrderByDescending(p => p.InteractionDate).Skip(model.StartIndex).Take(model.PageSize)
		            .AsQueryable()
		            .ProjectTo<Interaction>(mapper.ConfigurationProvider)
		            .ToListAsync()
            };

            return Ok(result.ThisPage, result.Total);
        }

        [HttpPost]
        public async Task<BaseResponse> Create(Interaction model)
        {
            if (ModelState.IsValid)
            {
                var entity = mapper.Map<DbInteraction>(model);
                entity.CreatedById = this.UserService.CurrentUserId;
                this.dbContext.Interactions.Add(entity);
                await this.dbContext.SaveChangesAsync();
                return Ok(mapper.Map<Interaction>(entity));
            }

            return Error();
        }

        [HttpPut]
        [Route("{Id}")]
        public async Task<BaseResponse> Edit([FromBodyAndRoute] Interaction model)
        {
            if (ModelState.IsValid)
            {
                var entity = await this.dbContext.Interactions.FindAsync(model.Id);
                if (entity == null)
                    return Error(OpResult.DoNotExist, "Interaction not found.");

                mapper.Map(model, entity);
                await this.dbContext.SaveChangesAsync();
                return Ok(mapper.Map<Interaction>(entity));
            }

            return Error();
        }

        [HttpDelete]
        [Route("{interactionId}")]
        public async Task<BaseResponse> Delete(Guid interactionId)
        {
            var entity = await this.dbContext.Interactions.FindAsync(interactionId);
            if (entity == null)
                return Error(OpResult.DoNotExist, "Interaction not found.");

            this.dbContext.Remove(entity);
            await this.dbContext.SaveChangesAsync();
            return Ok();
        }
    }
}

The GetInteractions operation takes an optional ContactId as part of the input model. This is so consumers can build two kinds of UIs for interactions:

1. Stand-alone: this interface will show an unfiltered list of interactions in recent-first order for all contacts belonging to the account. The ContactId will be null in such case and hence we’re querying by the OwnerUserId.
2. Popup: Invoked via the contacts UI, it could be a popup interface, and shall show filtered list of interactions in recent-first order for the contact user chose in the contacts UI.

In both Add and Edit operations, after checking that we’ve got a valid model, we use AutoMapper to transfer data from the service model to data model. CreatedById is assigned by us based on the CurrentUser during creation, and it’s read-only during modification for obvious reasons.

In the Delete operation, we perform a hard delete of the specified interaction. However, in the real system, you may rather perform a soft delete – marking the interaction as deleted rather than physically deleting it.

Authorization

Make sure you’ve gone through the authorization section of the previous step – building contact management – because here for interaction operations, we’ve leveraged the same concepts and tools of activity-data authorization (ADA) explained in detail over there.

First, let’s define the list of permissions for interaction related operations in the table below:

Now let’s define its implied permissions:

Similar to what we had done for contact’s implied permissions, we’ve defined implied permissions for interaction based on an increasingly privileged permission hierarchy. However, you may have noticed that we’ve defined three more records – get, delete and edit contact permissions, implying their interaction counterparts. This is because we feel that it’s logical to assume that if a user has these permissions on contacts, he should have the same permissions on their interaction records as well.

You may also notice that we haven’t defined the Customer role permission implying DeleteInteraction but we did it in case of DeleteContact. As you might have already guessed, it’s indirectly implied by being declared as an implied of DeleteContact!

You should now insert these new permissions and implied permissions data into the relevant tables as part of a migration.

First, add a new empty migration with the command,

add-migration InteractionPermissions

Next, replace the Up method which would be empty with the one below:

protected override void Up(MigrationBuilder migrationBuilder)
{
	var permissions = new[]
	{
		"('GetInteractions', 'Interaction', 'List Interactions', 0)", // general permission
		"('CreateInteraction', 'Interaction', 'Add new Interaction', 0)", // general permission
		"('EditInteraction', 'Interaction', 'Modify Interaction', 1)", // instance permission
		"('DeleteInteraction', 'Interaction', 'Delete Interaction', 1)", // instance permission
	};

	var impliedPermissions = new[]
	{
		"('CreateInteraction', 'GetInteractions')",
		"('EditInteraction', 'CreateInteraction')",
		"('DeleteInteraction', 'EditInteraction')",
		"('GetContacts', 'GetInteractions')",
		"('EditContact', 'EditInteraction')",
		"('DeleteContact', 'DeleteInteraction')"
	};

	var permissionsSql = new[]
	{
		@"insert into [dbo].[Permission](PermissionCode, EntityTypeCode, Description, Kind)values" + string.Join(",\r\n", permissions),
		@"insert into [dbo].[ImpliedPermission]
		(PermissionCode, ImpliedPermissionCode)values" + string.Join(",\r\n", impliedPermissions)
	};

	foreach (var script in permissionsSql)
	{
		migrationBuilder.Sql(script);
	}
}

Finally, execute the migration and insert the above data:

update-database

We now define a related references loader for interactionId the same way we did for contactId:

(Again, you define this method inside AuthDefinitions\ReferencesProvider.cs which comes as part of the template.)

public async Task<List<IdReference>> InteractionId(Guid interactionId)
{
	return await dbContext.Interactions
		.Where(x => x.Id == interactionId)
		.Select(x => new List<Guid> { x.Id, x.ContactId, x.Contact.OwnerId })
		.ToIdReferenceListAsync();
}

So, with above loader method, what we’re trying to say is that to authorize interactionId in Edit or Delete interaction operations for example, we can either use its contactId, contact’s ownerId or interactionId itself. We can just load the ownerId as we don’t plan to grant permit on interaction or contact entities specifically. But, we keep it this way to show you that those are also a possibility with related references. For example in financial systems, a read-only access can be granted as beneficiary (nominee) to users on financial accounts belonging to some other users.

After this, you can run the app and verify all the changes of this step.

Now, as Customer permit is loaded, CRUD permits related to both contact and interaction will also be recursively loaded with userId as the entityId for all of them. The related references loaders for both contactId and interactionId will help in authorizing any operation that refers these identifiers. Therefore, the user will be able to perform CRUD operations related to interactions on any contact that belongs to that user – without granting any new permit or writing any authorization checks explicitly.

Couple of more things to highlight before we conclude:

1. The contactId property in the GetInteractions operation will also be authorized if it’s a non-null value. On the other hand, if it’s null, presence of PossessesPermissionCodeAttribute will make sure that mere possession of the GetInteractions permission is enough to authorize the request.
2. We don’t use PossessesPermissionCodeAttribute on Add operation because it has ContactId identifier property as a required field.

Evaluation limit encountered

Tell me more

For more complex real-world examples of ADA in action, you can go through the SuperFinance tutorial (currently targeting only ASP.NET Core MVC). SuperFinance is a digital banking software as a service (SaaS) prototype with multiple levels of domain entities and many user roles, requiring even greater access-control options which is served very well by ADA.

Again, if you haven’t already, we recommend you go through both the design guide and the how-to article on ADA. Those two are quite comprehensive and give you deep understanding of activity data authorization concepts and tools that ASK offers.

Check out the ASP.NET Core Policy Authorization vs. ASPSecurityKit Activity-Data Authorization (ADA) guide (or the video that accompanies it) if interested in understanding the benefits ADA provides over built-in ASP.NET authorization options.

Download the sample

Refer the working sample project for this step of the tutorial on GitHub. Download the tutorial repo containing a stand-alone sample project for each step to try it locally on your PC.

Live demo

Visit https://SuperCRM-WebApi.ASPSecurityKit.net to play with a live demo built based on this tutorial.