Terms and concepts
Mobiz Authentication infrastructure.
Definition of terms and concepts in Mobiz Platform
Here we attempt to explain concepts in the Mobiz system as they appear from a Developer / API Client perspective.
Background on the Organization concept
Organization is absolutely a centerpiece in Mobiz Platform architecture.
An Organization represents a legal organizational entity. Such entities are usually represented by some kind of national-identifiers, like by Iceland’s government issued “kennitala”.
“Inside” the Mobiz Platform an Organization acts like a “container” for data. Indexed data from external systems is isolated into conceptual buckets per organization. Users can only access Organization’s data by having a Membership instance connecting the User to the corresponding Organization.
The word “Organization” is quite broad in nature. We use it to capture an “organizational entity”.
The following definition clearly describes the essence of our thinking.
Taken from http://differenceinbetween.blogspot.is/2012/09/difference-between-company-and.html
Each company is an organization, but not every organization is a business. This means that the organization is a broader term that encompasses a business.
A company usually associated with for-profit companies, organization, besides being a company, can also be a non-profit association.
Although the two terms are used interchangeably in the business (for profit) world (where a large company is also mentioned as an organization), officially, on paper and not a single firm (at least to my knowledge), regardless of size, refer to themselves as something more than a business.
Examples of companies include:
- Microsoft
- Apple
- Walmart
- A small IT company
- Any company (as firms intended to generate money)
Examples of organizations include:
- All companies listed
- NATO
- Red Cross
- World Bank
- Any college, school, etc.
As alway, these concepts hold quite well in general terms but can become confusing when you throw in all the hairy details of the real-world. This becomes quite apparent when we have stretched the Organization concept to include even a single person’s “operational entity” (PersonalAccount type of Organization) but more on that later.
Key concepts
Organization
- As already defined, Organization represents a legal entity.
- When working with data from ERP systems or similar business context, each Mobiz Organization points to a single business entity in the ERP system (usually referred to as ‘company’).
- In addition an Organization can also represent a single person legal representation. We refer to this as “Personal Account”. In such cases there might actually be more Users with some kind of membership against another user’s personal account. In examples like family relationship, husband and wife and similar.
User and OrganizationMembership
- Users represent people accessing the data belonging to one or more Organization.
- User can be a member of any Organization in Mobiz. Membership is represented by an OrganizationMembership instance. The membership will enable the user to access the data belonging to the Organization. Also the membership instance will hold details as for the security permissions and access privilege / role the User has against the corresponding Organization.
AdminDomain
AdminDomain is a concept introduced to enable separating Organizations into “Administration silos” against certain AdminDomain. Possible use cases for AdminDomain:
- SaaS application providing enterprise customer option to group several Organizations under a single “Administrative domain”.
- Code North partners can manage their own customers via their own branded AdminDomain.
Mobiz Scope
Scoping is a strong concept within the Mobiz platform. Essentially it refers to information or services which should never exist outside of a certain scope. For example services which read Organization data should be able to read data outside of the “scope” of the Organization which they were constructed. Same applies to User based services, AdminDomain, etc. For this we have the Mobiz Scope concept central in the platform design constructs.
Scoped Settings
Mobiz Platform provides a Settings service for storing scoped settings. This means the arbitrary settings can be stored against a combination of a key AND scope. Scope can be Organization, AdminDomain, User or System (global).
Mobiz platform supports storing settings as simple strings or JSON objects. Schema can be registered against a certain key to enforce that settings value stored under the given key adheres to the schema configured for the key.
MobizServiceCollection
Given that Mobiz Platform is built on .NET and that the ServiceCollection pattern for Dependency Injection is such a powerful DI implementation right at the heart of the .NET platform we of course build on this and extend the ServiceCollection with Mobiz Constructs.
Scoped Services
As described above the scope concept is a key security and abstraction construct to enforce isolation of services within the “scope” they are intended to serve. MobizServiceCollection is used to access scoped services to access features in a secure and clean manner with clear separation of concern.
Some thoughts on Organization Profile vs User Profile vs Accounts
Overview
Mobiz Platform is designed to handle Organization data. Therefore the basic constructs in Mobiz are Users which have access to Organizational data via Membership instances which define membership permissions / roles.
And of course, with any such elegant construct there always comes a scenario which breaks the design in one way or another.
Problem
In our case it was the project we did for Posturinn. In this case a high percentage of the shipments belongs to Individual people; Users not Companies. The default instinct was that we now needed to add support for data belonging to Users. But of course this was not the correct assumption.
Consider the fact that from Posturinn’s perspective (and any similar Enterprise Customer) the user is a legal entity which has some kind of social identification number, just as companies have.
Therefore it is not really the “user” who owns the data but it is the legal entity representing this user (as presented by the user’s SSN). Hopefully it makes sense. If not, try reading the above paragraphs again!
Actually when we thought of it in this way, it made great sense to keep the existing model and simply represent each user as an Organization. But there is an obvious problem here related to the fact that Users are clearly not Organizations and this caused us great concern as to how we could address this elegantly which resulted in deep introspective thinking and design discussions over a considerable period of time.
It is obviously counter-intuitive to think of Users as Organizations. Instead we wanted to introduce a concept called “LegalEntity” to represent this concept, a person which is actually a legal entity towards government and businesses, has its own government identification number but is not a company / business entity. As soon as we started to draft this new concept we realized that it was a 99% replica of the Organization object, only with a different name. And a new concept name which would always have to be explained anyway since it is not so self-explanatory.
Conclusion
We finally came to the conclusion to keep the Organization concept as the central concept for “legal entities having government identification numbers”. Instead of introducing a new LegalEntity concept we simply added a OrganizationType enum property to the Organization class which specifies the type of entity: PersonalAccount, Company, etc. This classification actually reflects the way public identity numbers are classified in Europe with clear distinction between personal and corporate ids. (Kennitala in Iceland).
Now this design allows for great flexibility, especially in relation to addressing the complex requirements of enterprise companies like posturinn where
User wants to access his own shipments.
User might want to share his account with his partner. (Now, easy to support by adding “sharing-membership” via Partner => (Sharing) Membership => Org representing User)
Companies want to manage the users having access to their shipments, even adding security restrictions or access limitations based on employee’s roles. Preferably synchronized with the company’s AD service to make sure employees’ access is disabled as soon as they leave their role. This can be supported with the Membership model.
So you can see we gain much power from keeping these concepts simple and clear.
Building on the concepts
Now, when we moved forward more concepts were added to the code.
UserProfile => For storing information related to the User in the business scenarios (as opposed to security). Example: Payment preferences, Delivery location for user shipments (Posturinn), etc.
User Profile is actually stored as Organization Profile for an Organization of type “PersonalAccount” which is (magically / implicitly) associated with each User.
User profile is accessed via the endpoint: “api/v1/my-profile”.
Organization Profile => For storing information related to the Organization which is currently selected / active.
Consider that Mobiz Platform provides strong support for “scope”. For example with Posturinn, a user might be using the app in the scope of his own shipments, or if the user is working for some companies, there might be more membership / “scopes” available for selecting. The profile view for PersonalAccount might look quite different from an Organization Profile view.
Hopefully all makes sense now. If not, try reading the whole document again!