SPIRE Setup Documentation

Overview

This setup deploys SPIRE as follows:

  • SPIRE Server on <SPIRE_SERVER_HOST>
  • SPIRE Agent on <SPIRE_AGENT_HOST>
  • Trust domain: <TRUST_DOMAIN>
  • Server/agent communication port: <SERVER_PORT>/tcp

How it works

SPIRE provides machine and workload identity.

The SPIRE Server on <SPIRE_SERVER_HOST> is the trust authority for the trust domain <TRUST_DOMAIN>.

The SPIRE Agent on <SPIRE_AGENT_HOST> attests to the server using x509pop with an X.509 certificate issued by an enterprise/internal CA.

Applications on <SPIRE_AGENT_HOST> do not talk directly to the SPIRE Server. They talk to the local SPIRE Agent over the local workload API socket <AGENT_SOCKET_PATH>.

The agent returns an X.509-SVID representing the workload identity.

Installation Instructions

  1. Install SPIRE binaries

Run on both hosts:

mkdir -p /opt/spire
cd /tmp
wget https://github.com/spiffe/spire/releases/download/v1.15.2/spire-1.15.2-linux-amd64-musl.tar.gz
tar zxf spire-1.15.2-linux-amd64-musl.tar.gz
cp -r spire-1.15.2/. /opt/spire/

On the SPIRE Server host:

ln -sf /opt/spire/bin/spire-server /usr/bin/spire-server

On the SPIRE Agent host:

ln -sf /opt/spire/bin/spire-agent /usr/bin/spire-agent

  1. Configure SPIRE Server

Create directories:

mkdir -p /opt/spire/conf
mkdir -p /opt/spire/data/server
mkdir -p /opt/spire/conf/x509pop

Place the CA bundle at:

/opt/spire/conf/x509pop/bundle.pem

Contents:

—–BEGIN CERTIFICATE—–
<REDACTED CA CERTIFICATE>
—–END CERTIFICATE—–
—–BEGIN CERTIFICATE—–
<REDACTED CA CERTIFICATE>
—–END CERTIFICATE—–
—–BEGIN CERTIFICATE—–
<REDACTED CA CERTIFICATE>
—–END CERTIFICATE—–

Create /opt/spire/conf/server.conf:

server {
bind_address = “0.0.0.0”
bind_port = “<SERVER_PORT>”
trust_domain = “<TRUST_DOMAIN>”
data_dir = “/opt/spire/data/server”
log_level = “INFO”
}

plugins {
DataStore “sql” {
plugin_data {
database_type = “sqlite3”
connection_string = “/opt/spire/data/server/datastore.sqlite3”
}
}

NodeAttestor “x509pop” {
plugin_data {
ca_bundle_path = “/opt/spire/conf/x509pop/bundle.pem”
}
}

KeyManager “memory” {
plugin_data {}
}
}

health_checks {
listener_enabled = true
bind_address = “127.0.0.1”
bind_port = “<HEALTH_PORT>”
}

Create /etc/systemd/system/spire-server.service:

[Unit]
Description=SPIRE Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/opt/spire/bin/spire-server run -config /opt/spire/conf/server.conf
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Start server:

systemctl daemon-reload
systemctl enable –now spire-server
systemctl status spire-server –no-pager

Validate server:

spire-server healthcheck

  1. Configure SPIRE Agent

Create directories:

mkdir -p /opt/spire/conf
mkdir -p /opt/spire/data/agent
mkdir -p /opt/spire/sockets
mkdir -p /opt/spire/conf/x509pop

Issue a certificate through your enterprise PKI platform. Download as OpenSSL format and split CRT/KEY files. Copy the node certificate to:

/opt/spire/conf/x509pop/agent.crt

Copy the node private key to:

/opt/spire/conf/x509pop/agent.key

The private key must be unencrypted PEM.

Set permissions:

chmod 700 /opt/spire/conf/x509pop
chmod 600 /opt/spire/conf/x509pop/agent.key
chmod 644 /opt/spire/conf/x509pop/agent.crt

Create /opt/spire/conf/agent.conf:

agent {
data_dir = “/opt/spire/data/agent”
log_level = “INFO”
trust_domain = “<TRUST_DOMAIN>”
server_address = “<SPIRE_SERVER_HOST>”
server_port = “<SERVER_PORT>”
socket_path = “<AGENT_SOCKET_PATH>”
insecure_bootstrap = true
}

plugins {
KeyManager “disk” {
plugin_data {
directory = “/opt/spire/data/agent”
}
}

WorkloadAttestor “unix” {
plugin_data {}
}

NodeAttestor “x509pop” {
plugin_data {
private_key_path = “/opt/spire/conf/x509pop/agent.key”
certificate_path = “/opt/spire/conf/x509pop/agent.crt”
}
}
}

Create /etc/systemd/system/spire-agent.service:

[Unit]
Description=SPIRE Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/opt/spire/bin/spire-agent run -config /opt/spire/conf/agent.conf
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Start agent:

systemctl daemon-reload
systemctl enable –now spire-agent
systemctl status spire-agent –no-pager

  1. Validate x509pop agent attestation

On the SPIRE Server host:

spire-server agent list

Expected result:

  • Agent attestation type is x509pop
  • Can re-attest is true
  • Parent ID format resembles:

spiffe://<TRUST_DOMAIN>/spire/agent/x509pop/<AGENT_HASH>

  1. Create workload registration entry

Use the current x509pop agent SPIFFE ID from spire-server agent list.

On the SPIRE Server host:

spire-server entry create \
-spiffeID spiffe://<TRUST_DOMAIN>/workload/<WORKLOAD_NAME> \
-parentID spiffe://<TRUST_DOMAIN>/spire/agent/x509pop/<AGENT_HASH> \
-selector unix:uid:0

This authorizes a root-owned process on the SPIRE Agent host.

  1. Fetch workload identity on the SPIRE Agent host

/opt/spire/bin/spire-agent api fetch x509 -socketPath <AGENT_SOCKET_PATH>

Expected SPIFFE ID:

spiffe://<TRUST_DOMAIN>/workload/<WORKLOAD_NAME>

  1. Write certs to disk for testing

Create destination directory:

mkdir -p /etc/spire/svid/test
chmod 700 /etc/spire/svid/test

Write files:

/opt/spire/bin/spire-agent api fetch x509 \
-socketPath <AGENT_SOCKET_PATH> \
-write /etc/spire/svid/test

Inspect output:

ls -l /etc/spire/svid/test

openssl x509 -in /etc/spire/svid/test/svid.0.pem -text -noout

  1. Reboot persistence validation

Reboot the SPIRE Agent host.

After reboot, validate:

systemctl status spire-agent –no-pager

ls -l <AGENT_SOCKET_PATH>

/opt/spire/bin/spire-agent api fetch x509 -socketPath <AGENT_SOCKET_PATH>

Expected behavior:

  • spire-agent starts automatically
  • Workload API socket exists
  • X.509-SVID fetch succeeds
  1. Operational notes
  • Current architecture: <SPIRE_SERVER_HOST> = SPIRE Server; <SPIRE_AGENT_HOST> = SPIRE Agent
  • Current trust domain: <TRUST_DOMAIN>
  • Current server/agent path: <SPIRE_AGENT_HOST> to <SPIRE_SERVER_HOST> on TCP <SERVER_PORT>
  • Current Workload API socket: <AGENT_SOCKET_PATH>
  • Current example workload selector: unix:uid:0
  • Current example workload identity: spiffe://<TRUST_DOMAIN>/workload/<WORKLOAD_NAME>

JWT

Create JWT registration on the SPIRE Server host:

spire-server entry create \
-spiffeID spiffe://<TRUST_DOMAIN>/workload/<JWT_WORKLOAD_NAME> \
-parentID spiffe://<TRUST_DOMAIN>/spire/agent/x509pop/<AGENT_HASH> \
-selector unix:uid:0

Fetch JWT-SVID from the SPIRE Agent host:

/opt/spire/bin/spire-agent api fetch jwt \
-socketPath <AGENT_SOCKET_PATH> \
-audience <JWT_AUDIENCE> \
-spiffeID spiffe://<TRUST_DOMAIN>/workload/<JWT_WORKLOAD_NAME>

Example output:

token(spiffe://<TRUST_DOMAIN>/workload/<JWT_WORKLOAD_NAME>):
<REDACTED JWT-SVID>

bundle(spiffe://<TRUST_DOMAIN>):
<REDACTED JWKS BUNDLE>

SPIRE OIDC Discovery Provider

On the SPIRE Server host:

mkdir -p /opt/spire-extras
cd /tmp
wget https://github.com/spiffe/spire/releases/download/v1.15.2/spire-extras-1.15.2-linux-amd64-musl.tar.gz
tar zxf spire-extras-1.15.2-linux-amd64-musl.tar.gz
cp -r spire-extras-1.15.2/ /opt/spire-extras/

ln -sf /opt/spire-extras/bin/oidc-discovery-provider /usr/bin/oidc-discovery-provider
mkdir -p /opt/spire-extras/conf/oidc-discovery-provider

Create certificate and key files:

/opt/spire-extras/conf/oidc-discovery-provider/tls.crt
/opt/spire-extras/conf/oidc-discovery-provider/tls.key

Set permissions:

chmod 644 /opt/spire-extras/conf/oidc-discovery-provider/tls.crt
chmod 600 /opt/spire-extras/conf/oidc-discovery-provider/tls.key

Create /opt/spire-extras/conf/oidc-discovery-provider/oidc-discovery-provider.conf:

log_level = “INFO”

domains = [“<OIDC_DISCOVERY_DOMAIN>”]

server_api {
address = “unix://<SPIRE_SERVER_API_SOCKET>”
}

serving_cert_file {
cert_file_path = “/opt/spire-extras/conf/oidc-discovery-provider/tls.crt”
key_file_path = “/opt/spire-extras/conf/oidc-discovery-provider/tls.key”
}

Create /etc/systemd/system/spire-oidc-discovery-provider.service:

[Unit]
Description=SPIRE OIDC Discovery Provider
After=network-online.target spire-server.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=/opt/spire-extras/bin/oidc-discovery-provider -config /opt/spire-extras/conf/oidc-discovery-provider/oidc-discovery-provider.conf
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Ping Integration

PingFederate Integration Note for SPIRE JWT Validation

Purpose

Configure PingFederate to trust and validate JWTs issued from the SPIRE environment.

SPIRE issuer details

Use these values:

  • Issuer: https://<OIDC_DISCOVERY_DOMAIN>
  • OIDC discovery URL: https://<OIDC_DISCOVERY_DOMAIN>/.well-known/openid-configuration
  • JWKS URL: https://<OIDC_DISCOVERY_DOMAIN>/keys

Trust model

PingFederate should validate JWT signatures using the JWKS published by the SPIRE OIDC Discovery Provider.

Ping does not need to call the SPIRE server directly for every token validation. It should use the discovery/JWKS metadata from the OIDC Discovery Provider.

Expected JWT characteristics

Issuer

Ping should require:

iss = https://<OIDC_DISCOVERY_DOMAIN>

Audience

Recommended audience value:

<PING_AUDIENCE>

Clients requesting JWT-SVIDs from SPIRE should request them with this audience.

Subject

The workload identity will be in:

sub

Example:

spiffe://<TRUST_DOMAIN>/workload/<WORKLOAD_NAME>

This is the primary identity claim Ping should use to identify the calling workload.

Recommended validation rules in Ping

Validate:

  • JWT signature against SPIRE JWKS
  • iss matches https://<OIDC_DISCOVERY_DOMAIN>
  • aud contains <PING_AUDIENCE>
  • token is within validity window (exp, iat)
  • sub is an allowed SPIFFE ID or matches allowed policy rules

Example workload identity currently in use

Current example SPIFFE ID:

spiffe://<TRUST_DOMAIN>/workload/<WORKLOAD_NAME>

Client-side JWT retrieval model

A workload on the SPIRE Agent host should obtain its JWT from the local SPIRE agent, not from the SPIRE server directly.

Local agent socket:

<AGENT_SOCKET_PATH>

Example operational flow

  1. Workload on the SPIRE Agent host requests a JWT-SVID from the local SPIRE agent.
  2. JWT-SVID is issued with:
  • issuer = https://<OIDC_DISCOVERY_DOMAIN>
  • audience = <PING_AUDIENCE>
  • subject = workload SPIFFE ID
  1. Workload presents JWT to PingFederate.
  2. PingFederate validates the JWT using SPIRE OIDC discovery/JWKS.
  3. PingFederate maps the SPIFFE workload identity to access policy, token issuance, or downstream application authorization.

Suggested placeholder legend

| Placeholder | Meaning |
|—|—|

| <SPIRE_SERVER_HOST> | SPIRE server hostname |

| <SPIRE_AGENT_HOST> | SPIRE agent hostname |

| <TRUST_DOMAIN> | SPIRE trust domain |

| <SERVER_PORT> | SPIRE server listener port |

| <HEALTH_PORT> | Health check port |

| <AGENT_SOCKET_PATH> | Local SPIRE Agent workload API socket |

| <AGENT_HASH> | x509pop parent/agent hash |

| <WORKLOAD_NAME> | Example X.509 workload name |

| <JWT_WORKLOAD_NAME> | Example JWT workload name |

| <JWT_AUDIENCE> | JWT audience used by client |

| <PING_AUDIENCE> | Audience PingFederate validates |

| <OIDC_DISCOVERY_DOMAIN> | Public/abstracted OIDC issuer hostname |

| <SPIRE_SERVER_API_SOCKET> | SPIRE server private API socket |

 

Leave a Reply

Your email address will not be published. Required fields are marked *