SPIRE Upstream Authority

This guide covers how to configure the Akeyless SPIRE Upstream Authority plugin for X.509 CA issuance used by SPIFFE Verifiable Identity Documents (SVIDs) and JWT-SVID key publication.

Prerequisites

• Akeyless Gateway v3.40.0 or later
• A running SPIRE Server and SPIRE Agent deployment
• An Authentication Method attached to a role with:
  • Create and List on relevant item paths for X.509 CA operations
  • Read on the item used for JWT signing keys (for JWT-SVID support)

Authentication

The following Authentication Methods are supported:

• API Key
• AWS IAM
• Azure
• GCP
• K8s

ℹ️

Note:

This guide uses API Key authentication for brevity. For production environments, use a cloud or workload-based Authentication Method where possible.

Create an API Key Authentication Method:

akeyless create-auth-method --name /Dev/Spire-Auth

Create an access role:

akeyless create-role --name /Dev/Spire-Role

Associate the Authentication Method to the role:

akeyless assoc-role-am --role-name /Dev/Spire-Role \
--am-name /Dev/Spire-Auth

Set role permissions for the SPIRE item path:

akeyless set-role-rule --role-name /Dev/Spire-Role \
--path /SPIRE/SVID/'*' \
--capability create \
--capability list \
--capability read

Grant Access Permissions on the Gateway

1. Sign in to the Akeyless Console with a Gateway admin account.
2. Open Gateways, and select the target Gateway.
3. Open Access Permissions, and select New.
4. Select the Authentication Method, and grant:
   • Admin permissions, or
   • Custom permissions that include the required key and item operations.

Download the Plugin

Download the latest Akeyless Upstream Authority plugin:

curl -o AkeylessUpstreamAuthority https://download.akeyless.io/Akeyless_Artifacts/Linux/spire/plugin/server/spire-upstream/spire-upstream-linux-amd64

curl -o AkeylessUpstreamAuthority https://download.akeyless.io/Akeyless_Artifacts/Linux/spire/plugin/server/spire-upstream/spire-upstream-linux-arm64

Download the checksum file and validate the binary:

curl -o spire-upstream.sha256 https://download.akeyless.io/Akeyless_Artifacts/Linux/spire/plugin/server/spire-upstream/spire-upstream-linux-amd64-sha256sumfile
sha256sum -c spire-upstream.sha256

Configure SPIRE Server

Edit conf/server/server.conf, and configure the UpstreamAuthority block:

UpstreamAuthority "akeyless_upstream" {
    plugin_cmd = "/path/to/AkeylessUpstreamAuthority"
    plugin_checksum = "sha256_of_plugin_binary"
    plugin_data {
        akeyless_gateway_url = "https://<your-gateway-url>:8000/api/v2"
        access_id = "<your_access_id>"
        access_key = "<your_access_key>"
        pki_cert_issuer_name = "<pki_issuer_name>"
        jwt_keys_secret_name = "<jwt_keys_secret_name>"
    }
}

Where:

• plugin_cmd is the path to the plugin binary.
• plugin_checksum is the SHA256 digest of that binary.
• akeyless_gateway_url is the Akeyless Gateway API v2 endpoint.
• access_id is the Authentication Method Access ID.
• access_key is required for API Key authentication.
• pki_cert_issuer_name is used for X.509 CA minting.
• jwt_keys_secret_name points to the Akeyless item that stores JWT signing keys for JWT-SVID publication.
• jwt_keys_retention_period (optional) - this indicates the interval with which to keep expired keys in the JWT SVIDs kept in the Akeyless secret. When not specified, the default 48 hours applies.
• jwt_keys_max_count (optional) - this configuration controls how many total JWT SVIDs will be kept in the Akeyless secret. When not specified, the default 10 applies.

For K8s, GCP, or Azure Authentication Methods, also set:

• k8s_auth_config_name
• gcp_audience (default: akeyless.io)
• azure_object_id

⚠️

Warning (TTL Configuration):

Ensure the requested SPIRE TTL values are lower than the configured TTL values in the Akeyless PKI Certificate Issuer.

Prepare Akeyless Resources

For X.509 CA minting, create a Classic Key and PKI Certificate Issuer.

Create a Classic Key:

akeyless create-classic-key \
--name /SPIRE/SVID/classic-key \
--alg RSA2048 \
--generate-self-signed-certificate true \
--gateway-url "https://<your-gateway-url>:8000" \
--certificate-ttl 7

Create a PKI Certificate Issuer:

akeyless create-pki-cert-issuer \
--name /SPIRE/SVID/pki-issuer \
--signer-key-name /SPIRE/SVID/classic-key \
--ttl 604800 \
--is-ca true \
--allowed-uri-sans spiffe://example.org/* \
--key-usage certsign,crlsign

For JWT-SVID support, jwt_keys_secret_name is optional. If this setting is omitted, the plugin creates and manages a default item named <pki_cert_issuer_name>-jwt-keys.

ℹ️

Info:

If jwt_keys_secret_name is set and the item does not exist, the plugin creates it during initialization. The plugin manages key rotation, key updates, and cleanup of expired keys.

Initialize SPIRE Server and Agent

Start SPIRE Server:

bin/spire-server run -config conf/server/server.conf &

Set the trust bundle path in conf/agent/agent.conf:

trust_bundle_path = "/path/to/certificate/file"

Generate an agent join token:

bin/spire-server token generate -spiffeID spiffe://example.org/myagent

Start SPIRE Agent:

bin/spire-agent run -config conf/agent/agent.conf -joinToken <token_string> &

ℹ️

Info (SPIFFE/SPIRE):

For full SPIRE bootstrap and registration steps, see Quickstart for Linux and macOS.