Principals

A principal is an authority-bearing subject in your system. It's a first-class entity that can hold capabilities and receive policies.

Identity vs Principal

Don't confuse identity with principal:

  • Identity: Who you are (from your identity provider)
  • Principal: What authority-bearing subject you are (in your system)

One identity can map to multiple principals. One principal maps to exactly one identity.

Example: Multiple Principals

Consider a developer who needs different authority for different environments:

  • Identity: alice (from GitHub)
  • Principal 1: alice-dev (development authority)
  • Principal 2: alice-prod (production authority)

Alice authenticates once (identity), but may have two separate authority contexts (principals).

Types of Principals

User Principals

Represent individual users:

  • alice
  • bob
  • carol

Service Principals

Represent services, agents, or applications:

  • payment-processor
  • billing-agent
  • ci-pipeline

Role-Based Principals

Represent roles within your organization:

  • role:admin
  • role:developer
  • role:viewer

Principal Creation

Principals are created explicitly. When a new user authenticates, you must:

  1. Verify the identity (identity provider)
  2. Check if a principal exists for this identity
  3. If not, create a new principal
  4. Link the identity to the principal

Principal Lifecycle

Create

A principal is created when a new identity authenticates for the first time.

Active

The principal can receive policies, be granted capabilities, and participate in delegations.

Suspend

A principal can be suspended. Suspended principals cannot authenticate or receive new authority.

Revoke

A principal can be revoked. All associated sessions and delegations are terminated.

Principal Attributes

Each principal has:

  • id: Unique identifier
  • identity_id: Link to the authenticated identity
  • tenant_id: Which tenant this principal belongs to
  • claims: Assertions from the identity provider
  • status: active, suspended, or revoked
  • created_at: When the principal was created

Claims on Principals

When an identity authenticates, claims are stored with the principal:

Claims can inform policy decisions. For example: "If claim:github_org == 'acme', grant api.admin".

Multi-Tenant Principals

Each principal belongs to exactly one tenant. A user can have multiple principals in different tenants.

Example

Alice's Tenant A principal: alice-tenant-a Alice's Tenant B principal: alice-tenant-b

When alice accesses Tenant A, she uses alice-tenant-a. When she accesses Tenant B, she uses alice-tenant-b.

Next Steps

  • Read Policies to learn how to grant capabilities to principals
  • Read Delegation to learn how principals can delegate authority
  • Read Authorization to see how principals are evaluated