Identity Configuration

The identity section defines how your node identifies itself to the Manta platform, including authentication credentials and node naming.

Overview

Identity configuration controls:

  • JWT authentication token for platform access

  • Node alias for friendly identification

  • Node ID generation strategy

  • Authentication and authorization

Configuration Example

[identity]
secured_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
alias = "gpu-worker-1"
random_id = false

Configuration Fields

secured_token

Type: string (required)

Description: JWT authentication token for node registration and communication

Details:

  • Obtained from the Manta manager or administrator

  • Contains node permissions and identity claims

  • Must be valid and not expired

  • Can reference environment variables

Examples:

# Direct token (not recommended for production)
secured_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Environment variable (recommended)
secured_token = "${MANTA_NODE_TOKEN}"

# With default fallback
secured_token = "${NODE_TOKEN:placeholder_token}"

Security Notes:

  • Never commit tokens to version control

  • Use environment variables in production

  • Rotate tokens regularly

  • Keep tokens secure and private

alias

Type: string (optional)

Default: None (auto-generated if not set)

Description: Human-friendly name for the node

Details:

  • Used for display in dashboards and logs

  • Should be unique within your deployment

  • Can contain letters, numbers, hyphens, underscores

  • Used as log file name base

Examples:

# Descriptive aliases
alias = "gpu-training-node-1"
alias = "edge-device-kitchen"
alias = "ml-workstation-lab"
alias = "prod-cpu-worker-03"

# Location-based
alias = "us-west-2-gpu-1"
alias = "datacenter-a-rack-5"

# Role-based
alias = "aggregator-primary"
alias = "trainer-node-2"

Naming Conventions:

  • Use descriptive names indicating purpose or location

  • Include hardware type if relevant (gpu, cpu, edge)

  • Add numbers for multiple similar nodes

  • Keep names reasonably short (< 50 characters)

random_id

Type: boolean

Default: false

Description: Whether to generate a random node ID on each startup

Details:

  • true: New random ID generated each time node starts

  • false: Uses alias as consistent node ID

Use Cases:

# Ephemeral nodes (containers, cloud instances)
random_id = true

# Persistent nodes (dedicated hardware)
random_id = false

Considerations:

  • Random IDs prevent node impersonation

  • Fixed IDs allow persistent node tracking

  • Random IDs complicate debugging

  • Fixed IDs simplify monitoring

Environment Variables

All identity fields support environment variable substitution:

# Set environment variables
export MANTA_NODE_TOKEN="eyJhbGciOiJIUzI1NiIs..."
export MANTA_NODE_ALIAS="prod-gpu-1"
export MANTA_RANDOM_ID="false"

# Reference in configuration
[identity]
secured_token = "${MANTA_NODE_TOKEN}"
alias = "${MANTA_NODE_ALIAS}"
random_id = ${MANTA_RANDOM_ID}

Token Management

Obtaining Tokens

JWT tokens are obtained from:

  1. Platform Administrator: Request from your admin

  2. Manager API: Generate programmatically

  3. Dashboard: Create via web interface

  4. CLI Tools: Use admin commands

Token Structure

JWT tokens contain:

{
  "sub": "node-abc123",
  "role": "node",
  "permissions": ["execute_tasks", "access_datasets"],
  "exp": 1234567890,
  "iat": 1234567800
}

Token Validation

Tokens are validated for:

  • Signature: Cryptographic verification

  • Expiration: Not past exp claim

  • Permissions: Required node permissions

  • Issuer: Trusted token source

Token Rotation

Best practices for token rotation:

  1. Regular rotation: Change tokens periodically

  2. Before expiration: Rotate before exp time

  3. Automated renewal: Use refresh tokens if available

  4. Secure distribution: Use secure channels

Security Best Practices

Token Security

  1. Never hardcode tokens in source code

  2. Use environment variables for production

  3. Restrict file permissions on config files

  4. Rotate tokens regularly (e.g., monthly)

  5. Monitor token usage for anomalies

# Secure configuration file
chmod 600 ~/.manta/nodes/production.toml

# Use environment variable
export MANTA_NODE_TOKEN="$(vault kv get -field=token secret/manta)"

Alias Security

  1. Avoid sensitive information in aliases

  2. Use consistent naming schemes

  3. Don’t expose infrastructure details

  4. Consider obfuscation for public deployments

# Good aliases (no sensitive info)
alias = "worker-1"
alias = "gpu-node-a"

# Avoid (exposes too much)
alias = "10.0.1.5-docker-gpu"
alias = "aws-i-0123456789-prod"

Common Configurations

Production Node

[identity]
secured_token = "${MANTA_PROD_TOKEN}"
alias = "prod-worker-${HOSTNAME}"
random_id = false

Development Node

[identity]
secured_token = "${MANTA_DEV_TOKEN:dev_token_here}"
alias = "dev-${USER}-node"
random_id = true

Edge Device

[identity]
secured_token = "${EDGE_TOKEN}"
alias = "edge-${DEVICE_ID}"
random_id = false

Container/Cloud

[identity]
secured_token = "${NODE_TOKEN}"
alias = "${HOSTNAME}"
random_id = true

Troubleshooting

Invalid Token Error

Error: Invalid or expired JWT token

Solutions:

  1. Check token hasn’t expired

  2. Verify token format (should start with “eyJ”)

  3. Ensure no extra whitespace

  4. Request new token from admin

Missing Token Error

Error: secured_token is required

Solutions:

  1. Set secured_token in configuration

  2. Export environment variable

  3. Run manta_node config init to set token

Duplicate Alias Error

Error: Node with alias 'worker-1' already exists

Solutions:

  1. Choose unique alias

  2. Enable random_id

  3. Use hostname in alias

  4. Add timestamp or random suffix

Validation

The identity configuration is validated for:

  1. Token presence: Must have secured_token

  2. Token format: Valid JWT structure

  3. Alias format: Valid characters only

  4. Boolean values: random_id must be true/false

Validation command:

manta_node config validate production

Integration Examples

Docker Deployment

# Dockerfile
FROM python:3.9

# Token passed at runtime
ENV MANTA_NODE_TOKEN=""
ENV NODE_ALIAS="${HOSTNAME}"

COPY config.toml /etc/manta/config.toml

CMD ["manta_node", "start", "/etc/manta/config.toml"]

# Run container
docker run -e MANTA_NODE_TOKEN="$TOKEN" \
           -e NODE_ALIAS="docker-node-1" \
           manta-node

Kubernetes Deployment

# Secret for token
apiVersion: v1
kind: Secret
metadata:
  name: manta-node-token
data:
  token: <base64-encoded-token>

---
# ConfigMap for configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: manta-node-config
data:
  config.toml: |
    [identity]
    secured_token = "${MANTA_NODE_TOKEN}"
    alias = "${POD_NAME}"
    random_id = true

See Also