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
- 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
- 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
- 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
- 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>
- 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.
- 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>
- 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
- 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
- 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
- Workload on the SPIRE Agent host requests a JWT-SVID from the local SPIRE agent.
- JWT-SVID is issued with:
- issuer = https://<OIDC_DISCOVERY_DOMAIN>
- audience = <PING_AUDIENCE>
- subject = workload SPIFFE ID
- Workload presents JWT to PingFederate.
- PingFederate validates the JWT using SPIRE OIDC discovery/JWKS.
- 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 |
