[Idea] Entity types, templates, and instances: unified model for entity creation and behavior

[sahandilshan]

Problem

Today, configuring how a class of entities (users, agents, or applications) behaves requires touching each entity individually. There is no central place to say "all contractors authenticate this way" or "support bots can only access these resources." When something needs to change, every instance must be updated one by one.

Idea

Introduce a three-level model:

• Type: a named category of entity (e.g., "Employee", "Contractor", "Support Bot"). Defines what entities of this kind look like and how they behave. Admins can create as many types as needed under each entity kind (User, Agent, Application).
• Template: defines how to create an instance of a type. Think of it as a creation recipe: what fields to pre-fill, what credentials to issue, and through which channel (admin invite, self-registration, bulk import, API). A type can have multiple templates.
• Instance: the actual entity (a specific user, agent, or application). It inherits behavior from its type and is created through one of the type's templates.

What lives where

On the Type (behavior):

• Flows: which login, registration, and recovery experiences entities of this type go through.
• Issuance policy: how entities of this type authenticate and obtain tokens (allowed authentication methods, grant types, token lifetimes).
• Default permissions: a base set of permissions that all entities of this type receive. Changing it on the type changes it everywhere, no need to update each entity.
• Access boundary: which resources this type of entity is allowed to reach, regardless of individual permissions.

Changing any of these on the type applies to all its instances.

On the Template (construction):

• Entry point: how entities get created (admin invite, self-registration, bulk import, API).
• Attribute defaults: pre-filled values for the type's fields.
• Credential provisioning: what credentials to issue at creation (secret, certificate, or none).

Templates only affect the moment of creation. Once an entity exists, its ongoing behavior comes from its type.

Overrides: An individual instance can override what its type defines (e.g., one specific agent gets a longer token lifetime). When this happens, the system should track the deviation so admins can see which instances differ from their type's baseline.

Open questions

1. Flow ownership: Today, applications decide the login flow. If types also define flows, how do they interact? Should the type's flow compose into the application's flow, or should one take precedence over the other?
2. Drift visibility: If instances can override, how do admins see which instances deviate from their type and on what?
3. Permissions delivery: Should the type assign permissions directly to all its instances, or should the type act as an automatic group that all its instances belong to?
4. Applications: Should applications also support admin-defined types like users and agents do, or remain as they are?
5. Access boundary vs permissions: Is "which resources a type can reach" a separate concept from permissions, or should it be part of the same permission model?

[sahandilshan]

Conceptual model

Types own behavior; templates own construction. Instances inherit from their type and may override with drift tracking.

[Dilusha-Madushan]

does Type extend, layer above, or replace the current entity type, and is it a single immutable classifier per instance or a set of attachable policy bundles?

is template resolved inside the onboarding flow like type is or applied by the service layer around it, and is the applied template recorded on the instance for provenance?

[sahandilshan]

does Type extend, layer above, or replace the current entity type, and is it a single immutable classifier per instance or a set of attachable policy bundles?

Haven't properly thought about whether it should extend, replace or modify the exisiting type. We have to think this through when gathering the requriemtns.

is template resolved inside the onboarding flow like type is or applied by the service layer around it, and is the applied template recorded on the instance for provenance?

Same as above. Need to properly decide while gathering the actual problems and when designing the solution

[thiva-k]

Hi @sahandilshan ,

Agree that we need a layer above instances to govern them together. But I don't think entity types should be that layer. Types are currently just a way to define a schema for subjects and bringing client configurations into this may defeat the purpose and further complicate the things. And having schemas for applications (application types) may add further complexity.

I would prefer to consider templates as a separate layer for both applications and agents, with the defaults you mentioned. Instances created through this templates can be governed together. We may need to have a clear boundary on what things can be configurable at the template-level and what are per-instance level overridable (e.g. credentials, etc.). WDYT?

[sahandilshan]

@thiva-k
Yeah agree. Based on @Dilusha-Madushan comments as well I wouldn't think we can use the exiting types as it is. Maybe we may need to introduce a new kind of type above the current type (Schema) and the schema is just what are the attributes that type has and we have to introduce new default behaviours, access and permissions for those. Something like below

or we may have go with the templates without complicating this.

[ThaminduDilshan]

I think the problem you're trying to highlight is a valid concern and having something like that will ease the configuration experience for a administrator or developer. But there are two aspects for this;

1. Improve the initial setup experience (creating resources for the first time)
2. Centrally govern the configurations for a set of entities

In our current implementation, OUs hold a set of default configurations (default flows) and get applied during console onboarding process (However currently these will only be applied during creation time and resource will get saved with the respective defaults. Hence later configurations require, configuring them individually at each entity/resource). This is somewhat into addressing the above 1st point.

Also in a discussion we had this week (#5219 (comment)), a requirement was discussed on having a set of governance configs in the user type level too. If we think of introducing some other layer, there will be a hierarchy of configurations and we may be overcomplicating it.

We need to consider governance aspect too and it has different levels.

1. Some configs can have a central value and is possible to be overridden at different levels.
   Ex: Application token configs can be customizable at each application as they wish, but fine to have a central config too
2. Some configs can have a central value and should only be customizable to a certain level. Complete overriding is not possible.
   Ex: Configure upper bound for some config, but individual instance can set their own values honoring to upper bound/ Centrally enforce 2 factor authentication, but different levels can customize options they offer for second factor.
3. Some configs need to be strictly enforced when set in a upper governance layer taking precedence over the lower level overrides.

Maybe we need to introduce a new concept/ or a difference laver to hold all of these, but IMO this expands to a more broader scope and need proper requirement gathering and ideation before arriving at a solution.