Skip to main content

Authenticate with JWT-SVID

This guide describes how to configure Strongbox to accept JWT-SVIDs for login. Each tenant can define one or more SPIFFE services, each with its own key source, validation rules, and SPIFFE ID mappings.

Strongbox supports SPIFFE authentication both inbound and outbound. External workloads can authenticate to Avassa using a JWT-SVID, and workloads started by Avassa can authenticate to external systems using JWT-SVIDs or X.509-SVIDs issued at login.

SPIFFE-based authentication federation​

SPIFFE allows federated authentication between trust domains. In Strongbox, this means two common flows:

  1. External workload authenticates to Avassa using a JWT-SVID. Configure one or more spiffe services to trust the external issuer (via JWKS or static keys), and map SPIFFE ID patterns to Avassa token policies. The workload then calls spiffe-login with its JWT-SVID.

  2. Avassa-managed workload authenticates to an external system using a JWT-SVID or X.509-SVID. Configure spiffe-settings for the tenant and enable SVID issuance in the token settings for the chosen login method. The external system must trust the CA or JWKS used by Avassa to issue SVIDs.

This enables federation both inbound (external -> Avassa) and outbound (Avassa -> external) using SPIFFE identities.

Configure a SPIFFE service using JWKS discovery​

Use a JWKS endpoint when the issuer publishes keys via HTTPS. The name is the SPIFFE trust domain, and is compared to the JWT iss claim and used to validate that sub begins with spiffe://<name>/.

supctl create strongbox authentication spiffe <<EOF
name: example
jwks-uri: https://spire.spire.telco.udc2.site.test/
jwks-use-root-ca-certs: true
jwks-tls-verify: false
jwks-refresh-interval: 5m
jwks-request-timeout: 5s
jwks-cache-max-age: 1h
allowed-algorithms:
  - es256
allowed-clock-skew: 1m
require-exp: true
require-aud: true
allowed-audiences:
  - avassa
spiffe-id-patterns:
  - name: spiffe://example.org/workload/*
    token-policies:
      - user
    token-explicit-max-ttl: 0s
    token-no-default-policy: false
    token-period: 0s
    token-type: default
    token-renewable: true
verbose-logging: true
distribute:
  to: all
EOF

If the JWKS endpoint uses a private CA, provide the CA chain and enable TLS verification:

supctl create strongbox authentication spiffe <<EOF
name: example2
jwks-uri: https://spire.spire.telco.udc2.site.test/
jwks-ca-cert: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
jwks-use-root-ca-certs: false
jwks-tls-verify: true
allowed-algorithms:
  - es256
require-exp: true
require-aud: true
allowed-audiences:
  - avassa
spiffe-id-patterns:
  - name: spiffe://example.org/workload/*
    token-policies:
      - user
distribute:
  to: all
EOF

Configure a SPIFFE service with static PEM keys​

Use static keys if you want to pin public keys or you cannot reach a JWKS endpoint.

supctl create strongbox authentication spiffe <<EOF
name: example3
pem-keys:
  - |
    -----BEGIN PUBLIC KEY-----
    MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMqF/WCzxlF47KAvHHprweGi8KkTS
    JxaYyk6HsdWjmW4l/RGDaNEpmM8mbh4ozbC0/cVzDDijFuGvuL2GHcu9sA==
    -----END PUBLIC KEY-----
allowed-algorithms:
  - es256
allowed-clock-skew: 1m
require-exp: true
require-aud: true
allowed-audiences:
  - avassa
spiffe-id-patterns:
  - name: spiffe://example.org/workload/*
    token-policies:
      - root
      - user
verbose-logging: true
distribute:
  to: all
EOF

Map SPIFFE IDs to token settings​

Each entry in spiffe-id-patterns describes which SPIFFE IDs are allowed to log in and which Avassa token settings should be applied. You can set policies, TTLs, and whether the default policy is included per pattern.

Login using a JWT-SVID​

Use spiffe-login with tenant, SPIFFE service name, and JWT-SVID:

supctl do spiffe-login telco example3 eyJhbGciOiJFUzI1NiIsImtpZCI6Im9YTVBOU3dHb285UlFFTlR6NkFFV2tqZmhBdUVvWGZrIiwidHlwIjoiSldUIn0.eyJhdWQiOlsiYXZhc3NhIl0sImV4cCI6MTc2OTcyNTU5MCwiaWF0IjoxNzY5NzIxOTkwLCJpc3MiOiJodHRwczovL29pZGMtZGlzY292ZXJ5LXByb3ZpZGVyLmV4YW1wbGUub3JnIiwic3ViIjoic3BpZmZlOi8vZXhhbXBsZS5vcmcvd29ya2xvYWQvZGVtbyJ9.WtoD7EB7tWFgJ5HX8k65wbC3l4Cg6bBPCe-fBkGx74FnZ2yc7CNDFBTvw7ITIYoEGx8CC4tMXF2VtNQCmZBalw
token: 706b6e36-d4b9-40c8-ac1f-0078f19d15ad
expires-in: 2764800
expires: 2026-03-02T21:26:38.067694Z
accessor: 608ab456-d4da-465d-b534-f34c2d6f14bb
creation-time: 2026-01-29T21:26:38.067694Z
renewal-time: 2026-01-29T21:26:38.067694Z

Issue JWT-SVID and X.509-SVID on login​

Strongbox can issue SPIFFE JWT-SVID and X.509-SVID when a user or workload logs in. Configure spiffe-settings for the tenant to select the issuing CA, signing key, and JWT issuer.

supctl merge strongbox spiffe-settings <<EOF
issuing-ca: spiffe-ca
jwt-signing-key: spiffe-jwt
jwt-issuer: https://spire.example.org
distribute:
  to: all
EOF

When spiffe-settings is configured, enable SVID issuance in the token settings for the login method you use (userpass, approle, OIDC, etc). The token settings include the audiences that should be placed in the generated JWT-SVID, and the X.509 certificate profile settings.

supctl merge strongbox authentication approles my-approle <<EOF
token-spiffe-jwt:
  jwt-audiences:
    - avassa
token-spiffe-x509:
  cert-type: server
  server-ext-usage: true
  client-ext-usage: false
  code-signing-ext-usage: false
  full-authority-key-identifier: false
EOF

The token-spiffe-jwt settings control the issued JWT-SVID:

  • jwt-audiences: list of audiences to include in the JWT-SVID.

The token-spiffe-x509 settings control the issued X.509-SVID:

  • cert-type: sets default certificate attributes for typical server or client usage.
  • server-ext-usage: adds the ServerAuth flag to Extended Key Usage.
  • client-ext-usage: adds the ClientAuth flag to Extended Key Usage.
  • code-signing-ext-usage: adds the CodeSigning flag to Extended Key Usage.
  • full-authority-key-identifier: includes key authority serial and name in addition to the key.

Using X.509-SVIDs for mTLS between workloads​

X.509-SVIDs can be used for mutual TLS between workloads. Each side presents its X.509-SVID and verifies the peer against the trusted SPIFFE CA bundle. The SPIFFE ID in the URI SAN is used for authorization (e.g., allow spiffe://example.org/ns/prod/sa/*).

The key steps are:

  • Issue X.509-SVIDs to workloads via token-spiffe-x509.
  • Distribute the issuing CA bundle to all parties that must verify peers.
  • Authorize based on SPIFFE IDs, not on DNS or CN values.