Agent Identity and Entity Model

[thiva-k]

Current Model

Requirement is to extend/modify this existing model to support agents as first-class entities.

Agent Requirements

Agents have characteristics and can function as these three entities:

1. User (egress)
2. Application (egress)
3. Resource (ingress)

Agent as an Application

• Agent can access resources on its own using credentials
  • e.g. client credentials, mTLS, private JWT
• Access delegation must be supported
  • Agent acts as an OAuth client
  • User delegates authority to agent
  • Agent performs actions on behalf of user

Agent as an User

• Agent logs into an application autonomously and performs actions.
• Agent performs operations as a user entity and has user-like identity and attributes

Agent as a Resource Server

• Access control for resources owned by the agent
• Agent manages its own resources
• RBAC for agent-owned resources

Agent credentials should be able to function as both user and OAuth client credentials in the traditional-sense.

Learnings from IS

• In IS, agents are modelled similar to users, mainly for the following requirements:
  • For supporting RBAC
  • Supporting attributes
• Cannot be modelled as application in IS since applications do not have RBAC, custom attributes, etc.
• Agent credentials function as user credentials
• Limitations:
  • Agents cannot act as OAuth clients natively, so cannot access resources on their own. Need an OAuth application created.
  • App-native APIs used in authorization code flow for agents to login on their own, into applications (to bypass UI)
  • Complex OBO flow using ‘act’ claims in tokens for user -> agent delegation
  • Agents not modelled as a resource-server (No native resource-server concept)

Proposed Entity Models for Thunder

Model 1(Agent/User IS an Entity)

• Common entity model for both users and agents
• This common entity model consists of:
  • Metadata (Entity ID, OU ID, created_at, etc.)
  • Entity Type (AGENT/USER)
  • State (active, disabled, etc.)
  • Entity Schema
  • Credentials
  • Roles association
  • Attributes
• Entity of AGENT type has an application and resource(optionally) associated with it.
• This association can be made through the same UUIDs (ENTITY_ID = APP_ID = RES_ID) or through references via attributes.
• RBAC for applications can be handled separately in this model if needed(e.g. instead of the “resource subscription”, we can have RBAC for applications)
• Groups can be considered as a collection of entities(agents/users)

Model 2(Application/Agent/User EXTENDS a Super Entity)

Model 1 may require maintaining the state, credentials of an entity in three places (Entity, Application and Resource)

• Applications, users and agents extend a “super entity” (term TBD)
• This super entity consists of core entity data:
  • Metadata (Entity ID, OU ID, created_at, etc.)
  • Entity Type
  • Entity schema(App?)
  • State
  • Credentials
  • Role associations
• An entity will have its core data in super entity and have other entity-specific data in Application/User/Agent model
  E.g.
  • Agent will store it’s:
    • Core data(credentials, state, etc.) in the super entity model
    • Agent specific attributes in Agent model
    • App specific configurations (e.g. login flow, branding etc.) in App model
  • Application will store it’s:
    • Core data (credentials, state, etc.) in super entity model
    • App specific configurations in App model
• Go does not naturally support the concept of inheritance. We should do struct or interface embedding (composition).
• Groups cannot be considered as a collection of entities. May have to special case users and agents for groups.
• May need to store application configuration in EntityDB. Also need to consider how to handle immutable configurations for this case.

Model 2.1 (Application/Agent/User/Resource EXTENDS a Super Entity)

Extends Model 2.0 and includes resources as an entity too.

Pros:

• Entities can have a representation as a resource natively (apps, users, agents can be resources by storing the resource specific definitions in the resource model).
• This representation can be used for runtime authorization checks and RBAC for these entities.
• E.g. If an App entity wants a representation as a resource (e.g. to enforce RBAC for the APIs it exposes), the entity model has a native representation and no need for a separate resource model.

Cons:

• Can resources be considered as an entity ?
• Unlike other entities there are no credentials, schema, role associations(?), state(?) for resources.
• Ideal to keep resources separate if entities are considered consumers of the resources.

Model 3 (Agent as an application)

• Consider agent as a wrapper on application or agent as a special ‘type’ of application.
• Application will natively have RBAC support in this model

Pros:

• Simplifies the overall entity model.
• Supports 80% requirement?
• No need of agent-native authentication APIs

Cons:

• Requirement 2 (considering agent as a user) cannot be satisfied. But this may not be a common use case and mechanisms for separation of agent activities from users are upcoming.

We will need to evaluate and finalize the model considering Thunder's future requirements too.

[thiva-k]

Agent requirements that should also be considered for future extensions in Thunder:

• Multiple credential type support (Private JWT, mTLS, etc.)
• Multiple OAuth Clients per application (e.g. MCP Clients per agent)
• Lifecycle support(along with other entities)
• Agent-specific authentication flow APIs
• Verifiable Credentials

Also other types of entities may be required to be supported if needed(e.g. devices, service accounts, workloads, etc.)

Based on this Model 1 or 2 should be able to satisfy the requirements. Whether application and/or resource should be included within the entity model or associated externally should be discussed.

Please let know your suggestions on this

[senthalan]

I don’t prefer Model 3. It solves the current problem, but Thunder is still new. This is a good time to build a base architecture that we can extend later, instead of solving only today’s need.

I believe Model 1 will eventually turn into Model 2. We will need to keep credentials and state of entity/application in one common place. The other option is syncing between them, but I don’t think syncing is a good idea. Because of this, I lean more towards Model 2.

From an access control point of view, Model 2.1 makes the most sense because it treats resources as entities. This makes the design flexible and easier to extend in the future.

Examples:

• Application as a resource
  In service-to-service communication, both services can be applications in Thunder. One application can act as a resource for another. This allows us to control which applications can access other applications and what permissions they have.

• User as a resource (family or delegated management)
  One user may manage other users. This also fits naturally into the same resource-based model.

If all resources extend from a common base entity, we can support these kinds of use cases easily in the future without special handling.

However, we still need to think about some implementation concerns:

• Entity configuration may need to be read from two databases
• We may not be able to use cascade deletes for cleanup
• We need a clear approach to support multiple user stores

These issues don’t block the approach, but we should understand and plan for them.