SPIFFE secrets engine (API)

Use the SPIFFE plugin to mint SPIFFE JWT-SVIDs. The example code below assumes you mounted the SPIFFE plugin at /spiffe. Since it is possible to enable secrets engines at any location, please update your API calls accordingly.

Create configuration

Configure the SPIFFE trust domain for the plugin.

Request parameters

• trust_domain (string: <required>) - The SPIFFE trust domain used by the plugin. You can omit the spiffe:// prefix.
• bundle_refresh_hint (int or time string: "1h") - The value to put as the refresh hint in trust bundles we publish. May not exceed key_lifetime/10.
• key_lifetime (int or time string: "24h") - How often to generate a new signing key. Uses duration format strings.
• jwt_issuer_url (string: optional) - The base URL to use for JWT issuer claims (iss), including https:// schema, host, and optional port. Must be reachable by whatever systems consume the JWTs. By default, Vault uses the cluster API address as the issuer URL. Vault appends the mount path and issuer endpoint to the issuer URL.
• jwt_signing_algorithm (string: "RS256") - Signing algorithm to use. Must be one of: RS256 (default), RS384, RS512, ES256, ES384, ES512.
• jwt_oidc_compatibility_mode (bool: false) - When set true, attempts to generate JWT SVIDs fail if the resulting SPIFFEID exceeds 255 chars, which is the limit for JWT sub claims in OIDC.

Sample payload

{
  "trust_domain": "example.org",
  "bundle_refresh_hint": "30m",
  "key_lifetime": "12h"
}

Read configuration

Fetch the SPIFFE configuration details.

Request parameters

None.

Sample response

{
  "bundle_refresh_hint": "3600",
  "jwt_issuer_url": "",
  "jwt_oidc_compability_mode": false,
  "jwt_signing_algorithm": "RS256",
  "key_lifetime": "86400",
  "trust_domain": "example.org"
}

Create role

Create or update a named role that specifies the content of JWTs.

Path parameters

• name (string: <required>) - The unique name of the SPIFFE role you want to update.

Request parameters

• template (string: <required>) - The template string to use for generating tokens in stringified JSON or base64 format.
• ttl (int or time string: "5m") - TTL of the tokens generated against the role. Uses duration format strings. Vault caps the TTLs of generated tokens with the lifespan of the current signing key.
• use_jti_claim (bool: false) - If true, Vault includes the jti claim in JWTs, which may impact their reusability.

Roles define a template in much the same way as identity tokens. As with identity tokens, some claims cannot be overridden by the template and are populated by the secrets engine:

• iss: Issuer URL is populated based on the global config setting jwt_issuer_url
• aud: Audience is populated by the JWT minting endpoint argument
• iat: Time of issue
• exp: Expiration time for the token (iat + ttl)
• jti: UUID that helps for audit trails and preventing replay attacks (rfc7519), present only if the role setting use_jti_claim is true

In addition to these standard claims, Vault includes a claim with the entity ID of the Vault client to assist in provenance:

• vault: {entity: {id: ENTITY_ID}}

Unlike with identity tokens, sub can (and must) be specified as either the SPIFFEID of the JWT SVID, or the path part of a SPIFFEID. The SPIFFE plugin automatically prepends path values with spiffe:// and the configured trust domain. Role creation fails if the parsed template does not have a sub claim. SVID minting fails if the expanded template is not a valid SPIFFEID, or does not have the configured trust domain.

Sample payload

{
  "template": "\"sub\": \"spiffe://example.com/sales/ {{identity.entity.aliases.auth_gcp_e3de7def.custom_metadata.spiffe_workload_id}}\""
}

Read role

Read the named SPIFFE role.

Path parameters

• name (string: <required>) - The unique name of the SPIFFE role you want to read.

Sample response

{
  "template": "\"sub\": \"spiffe://example.com/sales/{{identity.entity.aliases.auth_gcp_e3de7def.custom_metadata.spiffe_workload_id}}\"",
  "ttl": "300",
  "use_jti_claim": false
}

Delete role

Delete the named SPIFFE role.

Path parameters

• name (string: <required>) - The unique name of the SPIFFE role you want to delete.

List roles

List the names of all SPIFFE roles.

Request parameters

None.

Sample response

{
  "keys": [
    "example-role"
  ]
}

Mint JWT token

Creates and returns a JWT token based on the template associated with the role using JWT Compact Serialization format.

Request parameters

• audience (string: "") - The value to use for the aud claim in the JWT token.