Okay, let’s confront the elephant in the room… permissions and security trimming aren’t the most exciting topic when learning about portals – especially if you arrived here as part of your journey into mastering the Portal Web API. However, there’s no denying the fact that they’re absolutely necessary and foundational to a successful portal project that provides secure access to your organisation’s precious data and processes… so keep on reading!
In this write-up, I compare portal security to analogies from the security model in Dynamics 365 and model-driven apps. If you aren’t yet familiar with those, I highly recommend you start by reading Paddy Byrne’s excellent content on Securing the Dataverse over at Virtual Power Group
Similar to the security roles and privileges you’d configure and apply to users within Dynamics, entity permissions and web roles allow us to apply ‘Record-level’ and ‘role-based’ security for portals.
Users and ownership vs Contacts and relationships
One key difference is that the privileges within a Dynamics 365 security role are dictated based on ownership – the relationship a user, their team, business unit or organisation has with records in a particular table. Users and ownership mean nothing in the context of portal security.
As you may be aware, portal ‘users’ are entity permissions, the focus is the relationship that the logged in contact or their account has with the record.
For example, when you log in to your online banking portal, you expect to see the balance and statements for only your own bank accounts, and that no other customers get to see information about your bank accounts.
In order to be security-trimmed on the portal, each entity must either:
- Have a direct link (lookup) to the Contact or Account entity (think a case for a given account or contact)
- Be a child record of an entity that has a direct link (lookup) to the Contact or Account entity (think notes and activities related to a case)
Entity permissions are equivalent to the entity-level privileges within a security role in Dynamics
The Scopes for Entity Permissions are similar to the level for privileges within Security Roles
Global scope is similar to Organisation level privileges
Account scope is similar to Business Unit level privileges in that the user / contact doesn’t necessarily own the record directly but belongs to the ‘team’ that does
Contact scope is equivalent to User level privileges
|Global||Allows all portal users to see / interact with all records, no relationship required, no security trimming applied||Allow everyone to see and select all the product you offer|
|Contact||Allow portal users to see / interact with records that they have a direct relationship with||Personal bank accounts where they (the contact) are the customer / account holder|
|Account||Allow portal users to see / interact with records that their account has a direct relationship with||Invoices where the portal user (contact)’s account is the customer|
|Parent||Allow portal users to see / interact with child records associated with a record with which they (the contact) or their account has a direct relationship with||Attachments regarding a bank account where either:
a. the portal user (contact) is the customer / account holder
b. the portal user’s account is the customer / account holder
|Self||Allow the portal users to see / interact with their own contact record||Logged in portal users (contacts) are able to amend their contact information and preferences on the Profile page in the portal|
Once the scope is defined, privileges allow you to control the level of access they have to their records – what can they ‘do’ with those records?
|Read||See existing records||View a list of cases|
|Write||Edit existing records||Update an existing case|
|Create||Create new records||Raise a new case|
|Delete||Delete existing records||Delete portal comments|
|Append||Relate records for this entity to other records||Attaching a document to an application form (The Append privilege is required on the entity that the portal user is attaching ‘from’ i.e. the document)|
|Append To||Relate records to this entity||Attaching a document to an application form (The Append To privilege is required on the entity that the portal user is attaching ‘to’ i.e. the application)|
Note: unlike security roles, granting entity permissions e.g. for note entity (parent scope) is specific to that relationship and doesn’t mean the user then has permissions to see all notes ‘across the board’. You’ll need to set up separate permissions for each relationship e.g. access to notes related to Cases within contact scope doesn’t provide that same contact access to notes relating to Opportunities.
So that’s how we define the permission but how do we give someone those privileges?…
The Web Roles sub-grid allows you to specify which web roles a portal user must have in order to receive this entity permission.
Please note that you can’t add web roles until you’ve first saved the entity permission record. It’s very important that you remember to do so otherwise the permission isn’t applied to anyone.
Where entity permissions are like privileges within a security role, a web role is the equivalent to a security role.
By default, the portal solution includes 3 web roles; authenticated users, anonymous users and administrators:
Out of the box web roles
- Anonymous users (everyone, regardless of whether they exist as a contact / have an account / are logged into the portal. This might be useful for lead generation or a contact form)
- Authenticated users (contacts that have logged in to the portal)
- Administrators (enables front-end editor and ability to refresh the cache and rebuild search index)
There’s nothing you need to do to manually assign someone the anonymous users or authenticated user web roles, they’re given automatically based on whether the user (Contact!) is logged into the portal. However, you need to decide who you wish to give administrator access to.
For customer self-service, the most commonly used web role for entity permissions tends to be Authenticated Users, meaning that only logged in portal users receive this permission.
If, for example, your portal has an enquiry form allowing the public to submit leads without the pre-requisites of registering for and logging into the portal, you would add the Anonymous Users web role to the entity permissions for the Lead entity.
In addition to these out-of-the-box web roles, we can create any number of custom web roles to provide more granular security trimming. Here are some examples of where you might apply these…
Membership tiers / support plans e.g.
- Spotify free vs Spotify premium
- Gold support plan vs Silver support plan
Privileges for a specific business process
This could potentially a one-off entitlement or temporary access e.g. as a mortgage provider, only grant access to the conveyancing portal until the house sale / purchase has completed)
- Case management
- Finance applications
- Mortgage conveyancing
- Each entity permission is a like a key
- A web role is like giving someone a set of keys
Here are some more examples of where it might make sense to create additional / custom web roles for your portal project. Think of how the required level of access and level of visibility within the same web app would differ between the following personas:
Teacher vs Student vs Parent
Landlord vs Tennant vs Guarantor vs Solicitor
Listeners / Subscribers vs Record Label Staff vs Spotify staff
Further reading – the sequel
Interested in learning more? Would you like to see some examples to help consolidate your learning? Check out part 2 where I break down the entity permissions that come out-of-the-box with the Customer Self-Service starter portal