IDP:REG Token

Overview

The IDP:REG (Identity Provider Registration) token enables federated identity registration. It allows a registrar to request identity creation on a remote Identity Provider (IDP) instance, enabling community-owned identities and cross-instance identity management.

Use Cases

Community-Owned Identities: A community owner creates identities under their domain on a remote IDP
Federated Registration: Registrar on instance A creates identities on IDP instance B
Bulk Identity Provisioning: Automated identity creation for organizations

Token Structure

Field	Type	Required	Description
`iss`	identity	Yes	The registrar’s identity
`aud`	identity	Yes	The IDP instance to register on
`iat`	timestamp	Yes	Issue time
`k`	string	Yes	Signing key ID
`t`	string	Yes	`IDP:REG`
`c`	object	Yes	Registration content (see below)

Content Schema

Field	Type	Required	Description
`id_tag`	string	Yes	Identity to register (e.g., `alice.cloudillo.net`)
`email`	string	No	Email address (required if no `owner_id_tag`)
`owner_id_tag`	string	No	Owner identity for community-owned identities
`issuer`	string	No	Issuer role: `registrar` (default) or `owner`
`expires_at`	number	No	Identity expiration timestamp

Content-Addressing

This token is content-addressed using SHA-256:

The entire JWT token (header + payload + signature) is hashed
Action ID format: a1~{base64_hash}
See Content-Addressing & Merkle Trees for details

Database Key

The database key for an IDP:REG token is [type, issuer, audience, content.id_tag]

Purpose: This key ensures that only one registration request exists for a given identity from a given registrar. The key components are:

type: Token type (IDP:REG)
issuer: Registrar identity
audience: Target IDP instance
content.id_tag: The identity being registered

Behavior Flags

Flag	Value	Description
`broadcast`	false	Not broadcast to followers
`allow_unknown`	true	Allows additional content fields
`requires_acceptance`	false	Processed immediately on receipt

Authorization

Role	Can Create	Can Receive
Registrar	Yes (authenticated)	-
IDP Instance	-	Yes (any)

Issuer Roles

The issuer field in content determines the relationship:

Role	Description
`registrar`	Default. Registrar manages identity until activation
`owner`	Issuer is the owner of the identity

After activation, registrar control is revoked - only the owner retains access.

Example

A community owner (community@cloudillo.net) registers a new member identity:

{
  "iss": "community@cloudillo.net",
  "aud": "cl-o.cloudillo.net",
  "iat": 1735000000,
  "k": "20250101",
  "t": "IDP:REG",
  "c": {
    "id_tag": "alice.cloudillo.net",
    "email": "alice@example.com",
    "owner_id_tag": "community@cloudillo.net",
    "issuer": "owner",
    "expires_at": 1766536000
  }
}

Field	Value
iss	community@cloudillo.net
aud	cl-o.cloudillo.net
iat	2025-01-02T00:00:00Z
k	20250101
t	IDP:REG
c.id_tag	alice.cloudillo.net
c.owner_id_tag	community@cloudillo.net

Processing Flow

1. Registrar creates IDP:REG action
   ↓
2. Action sent to IDP instance (/api/inbox)
   ↓
3. IDP verifies:
   - JWT signature
   - Issuer has permission to create identities
   - Domain matches IDP's domain
   ↓
4. Identity created with status "pending"
   ↓
5. IDP sends activation link directly to identity owner (via email)
   ↓
6. Identity owner activates via /api/idp/activate
   ↓
7. Identity status becomes "active"

Federation Diagram

sequenceDiagram
    participant R as Registrar
    participant IDP as IDP Instance
    participant O as Identity Owner

    R->>R: Create IDP:REG JWT
    R->>IDP: POST /api/inbox {token}
    IDP->>IDP: Verify JWT signature
    IDP->>IDP: Create identity (pending)
    IDP-->>R: 200 OK

    IDP->>O: Send activation email/link
    O->>IDP: POST /api/idp/activate {refId}
    IDP->>IDP: Activate identity
    IDP-->>O: 200 OK {identity}

Community Ownership

When owner_id_tag is provided:

The identity is owned by the specified community/user
The registrar only has control while status is pending
After activation, only the owner can manage the identity
Email is optional (owner relationship is the primary identifier)

Security Considerations

Signature Verification

The receiving IDP verifies:

JWT signature matches issuer’s public key
Issuer is allowed to create identities on this IDP
Requested id_tag domain matches IDP’s domain

Domain Validation

The id_tag in content must match the IDP’s domain:

Request: alice.cloudillo.net → IDP: cloudillo.net ✅
Request: alice.other.net → IDP: cloudillo.net ❌ (rejected)

Registrar Control Limits

Registrar control is time-limited:

Full control while identity status is pending
No control after identity is activated
Prevents registrar from managing user’s active identity