Identity & SSO

This document covers integration with identity providers (IDPs), JWT validation, JWKS caching, external IDs, and directory sync.

Overview

Enterprise networks can integrate with external identity providers (IDPs) to centralize authentication. Agents can present tokens from an organization’s IDP, such as OIDC, SAML, Entra ID, LDAP, or a custom webhook. The registry validates these tokens before granting access, as an alternative to Pilot’s built-in Ed25519 keys.

Identity integration is configured per-network. Each network can have its own IDP configuration.

Supported providers

OIDC (`oidc`): OpenID Connect. A standard for JWT-based SSO used by Auth0, Okta, Google, and others.
SAML (`saml`): Security Assertion Markup Language. An XML-based standard for enterprise SSO.
Entra ID (`entra_id`): Microsoft Entra ID (formerly Azure AD). A native integration for Microsoft environments.
LDAP (`ldap`): Lightweight Directory Access Protocol. For on-premises directory servers.
Webhook (`webhook`): A custom HTTP callback to a verification endpoint for non-standard systems.

Configuration

Configure an identity provider with the `set_idp_config` protocol command.

# OIDC example
{
  "command": "set_idp_config",
  "type": "oidc",
  "url": "https://accounts.example.com/.well-known/openid-configuration",
  "client_id": "pilot-network-prod",
  "admin_token": "your-admin-token"
}

The IDP configuration is stored in the registry and persists across restarts. The IDP can also be set through a blueprint using the `identity_provider` field.

To query the current configuration:

{
  "command": "get_idp_config",
  "admin_token": "your-admin-token"
}

An `idp.configured` audit event is emitted when the IDP is set or changed.

JWT validation

The registry has built-in JWT validation for two algorithms:

RS256: Uses an RSA public key from a JWKS. For standard OIDC/OAuth2 providers.
HS256: Uses a shared secret. For simple integrations and internal services.

Validate a token with the `validate_token` protocol command:

{
  "command": "validate_token",
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "admin_token": "your-admin-token"
}

The command returns `valid` (boolean), `claims` (the decoded JWT claims if valid), or `error` (a string describing the validation failure).

The validator checks the following claims:

Signature: Verified against the JWKS public key (RS256) or shared secret (HS256).
Expiration (`exp`): The token must not be expired.
Not-before (`nbf`): The token must not be used before its valid time.
Issued-at (`iat`): The timestamp is checked for reasonableness.
Issuer (`iss`): Must match the configured IDP URL.
Audience (`aud`): Must match the configured client ID.

JWKS caching

For RS256 tokens, the registry fetches the provider’s JSON Web Key Set (JWKS) to get public keys for signature verification. JWKS responses are cached.

Cache TTL: 5 minutes
Max response size: 64 KB
Key matching: By `kid` (Key ID) header in the JWT
Refresh: Automatic on cache expiry, or on-demand if a `kid` is not found in the cached set.

If the JWKS endpoint is unreachable and the cache has expired, validation fails. The registry does not accept unverified tokens.

Security

The validator enforces the expected algorithm based on configuration to prevent algorithm confusion attacks. The `alg` header in the JWT must match the configured algorithm.

A 60-second clock skew tolerance is applied to all time-based claims (`exp`, `nbf`, `iat`) to accommodate minor clock differences between the IDP and the registry.

Webhook identity

For systems that do not support OIDC or SAML, a webhook identity provider can be configured. The registry sends an agent’s credentials to an HTTP endpoint, which returns an approval or rejection.

# Configure a webhook IDP
{
  "command": "set_idp_config",
  "type": "webhook",
  "url": "https://auth.example.com/verify-agent",
  "admin_token": "your-admin-token"
}

The endpoint receives a POST request with the agent’s identity information and must return a JSON response indicating whether the agent is authorized.

External IDs

Agents can be mapped to external identity systems using external IDs.

# Set an external ID for an agent
{
  "command": "set_external_id",
  "node_id": 5,
  "external_id": "[email protected]",
  "admin_token": "your-admin-token"
}

# Look up an agent’s identity
{
  "command": "get_identity",
  "node_id": 5,
  "admin_token": "your-admin-token"
}

External IDs are free-form strings, such as email addresses or UPNs. They are stored in the registry and included in audit events. An `identity.external_id_set` audit event is emitted on change.

Directory sync

Directory sync pushes entries from an external directory to the registry, which automatically provisions and deprovisions network members.

The sync operation is performed with the `directory_sync` command.

{
  "command": "directory_sync",
  "network_id": 1,
  "entries": [
    {
      "external_id": "[email protected]",
      "node_id": 5,
      "role": "admin",
      "tags": ["frontend", "us-east"]
    },
    {
      "external_id": "[email protected]",
      "node_id": 8,
      "role": "member"
    }
  ],
  "remove_unlisted": true,
  "admin_token": "your-admin-token"
}

The sync operation performs the following actions:

Matches entries: Each entry is matched to a registered node by `node_id`.
Joins to network: Nodes not already in the network are added.
Maps roles: The `role` field sets the RBAC role (admin or member). The owner role cannot be assigned through sync.
Sets external IDs: The `external_id` field is stored for identity mapping.
Applies tags: The optional `tags` field sets the node’s capability tags.
Removes unlisted: If `remove_unlisted` is true, members not in the `entries` list are removed from the network.

Directory sync supports role pre-assignment. When a new member is added through sync, they receive their assigned role immediately instead of defaulting to the member role.

Query the sync status with the `get_directory_status` command.

{
  "command": "get_directory_status",
  "network_id": 1,
  "admin_token": "your-admin-token"
}

The command returns the last sync timestamp, number of entries processed, and any errors. A `directory.synced` audit event is emitted after each sync.