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

Content field names are camelCase.

Field Type Required Description
idTag string Yes Identity to register (e.g., alice.cloudillo.net)
email string No Email address (required if no ownerIdTag)
ownerIdTag string No Owner identity for community-owned identities
issuer string No Issuer role: registrar (default) or owner
address string No Identity address; use auto to use the client’s IP
lang string No Preferred language for emails (e.g., hu, de)
Note

The pending identity’s expiration is set server-side (24 hours). It is not supplied as a content field.

Content-Addressing

This token is content-addressed using SHA-256:

Database Key

The database key for an IDP:REG token is [t, iss, aud, content.idTag]

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

  • t: Token type (IDP:REG)
  • iss: Registrar identity
  • aud: Target IDP instance
  • content.idTag: 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": {
    "idTag": "alice.cloudillo.net",
    "email": "alice@example.com",
    "ownerIdTag": "community@cloudillo.net",
    "issuer": "owner"
  }
}
Field Value
iss community@cloudillo.net
aud cl-o.cloudillo.net
iat 2025-01-02T00:00:00Z
k 20250101
t IDP:REG
c.idTag alice.cloudillo.net
c.ownerIdTag 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 ownerIdTag is provided:

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

Security Considerations

Signature Verification

The receiving IDP verifies:

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

Domain Validation

The idTag 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

See Also