JWT Authentication

A JWT auth role defines claim constraints and token settings for entities authenticating via a jwt-auth configuration.

Create a new jwt auth

SecurityaccessToken

Request

query Parameters

validate

string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"

Request Body schema:
application/yaml

One of:

discovery-url	string OIDC discovery URL used to fetch the issuer's public keys. The well-known OpenID configuration document is fetched from this URL (appending /.well-known/openid-configuration if not already present), and the JWKS URI is extracted from that document. Common for OIDC providers and GitLab CI/CD.
jwks-ca-cert	string <ca-cert> One or more root certificates in PEM format. CA certificates, in PEM format, to use when validating the TLS connection to the discovery and JWKS endpoints. Multiple certs may be added as one string. By default, the system root CA bundle is used (see jwks-use-root-ca-certs). Configure this leaf when using a private CA. TLS verification can be disabled entirely with jwks-tls-verify false.
jwks-use-root-ca-certs	boolean Default: true Use the system root CA certificate bundle when validating the TLS certificate of the discovery and JWKS endpoints.
jwks-server-name-indication	string Override the TLS SNI hostname used when connecting to the discovery and JWKS endpoints. By default the hostname from discovery-url is used.
jwks-tls-verify	boolean Default: true Verify the TLS certificate of the discovery and JWKS endpoints. Should only be set to false in test environments, never in production.
jwks-refresh-interval	string <duration> Default: "5m" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` How often to refresh the JWKS from the discovery endpoint.
jwks-request-timeout	string <duration> Default: "5s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Timeout for JWKS retrieval.
jwks-cache-max-age	string <duration> Default: "1h" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Max time to use cached keys if JWKS fetch fails.
name	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ Name of this JWT auth configuration.
allowed-algorithms	Array of strings <enumeration> `es256` `es384` `rs256` JOSE algorithms accepted for signatures, e.g. 'es256', 'es384', 'rs256'. The default set is: 'es256', 'es384', 'rs256'.
allowed-clock-skew	string <duration> Default: "60s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Allowed clock skew when validating exp/nbf/iat.
require-exp	boolean Default: true Require 'exp' claim.
issuer	string Expected 'iss' claim value. If not set, the 'iss' claim is not validated and any issuer is accepted.
verbose-logging	boolean Default: false Enable verbose logging for JWT authentication attempts. Do not enable in production. The log entries will appear in the volga topic system:logs on the site where the logging occurred.
	to (object) or sites (object) or deployments (object)

Responses

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict (instance exists)

503

Service Unavailable (strongbox sealed)

post/v1/config/strongbox/authentication/jwt

Request samples

Payload

name: example
discovery-url: https://idp.example.test:8443
jwks-ca-cert: |
  -----BEGIN CERTIFICATE-----
  MIIB...REPLACE_ME...==
  -----END CERTIFICATE-----
jwks-use-root-ca-certs: false
jwks-server-name-indication: idp.example.test
jwks-tls-verify: true
jwks-refresh-interval: 5m
jwks-request-timeout: 5s
jwks-cache-max-age: 1h
allowed-algorithms:
  - es256
allowed-clock-skew: 1m
require-exp: true
issuer: https://idp.example.test:8443
verbose-logging: false
distribute:
  to: all

Retrieve the configuration of all jwt auths

SecurityaccessToken

Request

query Parameters

fields	string Retrieve only requested fields from the resource See section fields
where	string Retrieve only items matching the given expression. See section where
validate	string <enumeration> Validate the request but do not actually perform the requested operation Value: "true"
keys	string <enumeration> Retrieve only the keys for the list Value: "true"
count	string <enumeration> Retrieve only the number of elements in the list Value: "true"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/authentication/jwt

Response samples

- name: example
  discovery-url: https://idp.example.test:8443
  jwks-ca-cert: |
    -----BEGIN CERTIFICATE-----
    MIIB...REPLACE_ME...==
    -----END CERTIFICATE-----
  jwks-use-root-ca-certs: false
  jwks-server-name-indication: idp.example.test
  jwks-tls-verify: true
  jwks-refresh-interval: 5m
  jwks-request-timeout: 5s
  jwks-cache-max-age: 1h
  allowed-algorithms:
    - es256
  allowed-clock-skew: 1m
  require-exp: true
  issuer: https://idp.example.test:8443
  verbose-logging: false
  distribute:
    to: all

Update a jwt auth

SecurityaccessToken

Request

path Parameters

jwt-auth-name

required

string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Name of this JWT auth configuration.

query Parameters

validate

string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"

Request Body schema:
application/yaml

One of:

discovery-url	string OIDC discovery URL used to fetch the issuer's public keys. The well-known OpenID configuration document is fetched from this URL (appending /.well-known/openid-configuration if not already present), and the JWKS URI is extracted from that document. Common for OIDC providers and GitLab CI/CD.
jwks-ca-cert	string <ca-cert> One or more root certificates in PEM format. CA certificates, in PEM format, to use when validating the TLS connection to the discovery and JWKS endpoints. Multiple certs may be added as one string. By default, the system root CA bundle is used (see jwks-use-root-ca-certs). Configure this leaf when using a private CA. TLS verification can be disabled entirely with jwks-tls-verify false.
jwks-use-root-ca-certs	boolean Default: true Use the system root CA certificate bundle when validating the TLS certificate of the discovery and JWKS endpoints.
jwks-server-name-indication	string Override the TLS SNI hostname used when connecting to the discovery and JWKS endpoints. By default the hostname from discovery-url is used.
jwks-tls-verify	boolean Default: true Verify the TLS certificate of the discovery and JWKS endpoints. Should only be set to false in test environments, never in production.
jwks-refresh-interval	string <duration> Default: "5m" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` How often to refresh the JWKS from the discovery endpoint.
jwks-request-timeout	string <duration> Default: "5s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Timeout for JWKS retrieval.
jwks-cache-max-age	string <duration> Default: "1h" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Max time to use cached keys if JWKS fetch fails.
name	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ Name of this JWT auth configuration.
allowed-algorithms	Array of strings <enumeration> `es256` `es384` `rs256` JOSE algorithms accepted for signatures, e.g. 'es256', 'es384', 'rs256'. The default set is: 'es256', 'es384', 'rs256'.
allowed-clock-skew	string <duration> Default: "60s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Allowed clock skew when validating exp/nbf/iat.
require-exp	boolean Default: true Require 'exp' claim.
issuer	string Expected 'iss' claim value. If not set, the 'iss' claim is not validated and any issuer is accepted.
verbose-logging	boolean Default: false Enable verbose logging for JWT authentication attempts. Do not enable in production. The log entries will appear in the volga topic system:logs on the site where the logging occurred.
	to (object) or sites (object) or deployments (object)

Responses

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

patch/v1/config/strongbox/authentication/jwt/{jwt-auth-name}

Request samples

Payload

name: example
discovery-url: https://idp.example.test:8443
jwks-ca-cert: |
  -----BEGIN CERTIFICATE-----
  MIIB...REPLACE_ME...==
  -----END CERTIFICATE-----
jwks-use-root-ca-certs: false
jwks-server-name-indication: idp.example.test
jwks-tls-verify: true
jwks-refresh-interval: 5m
jwks-request-timeout: 5s
jwks-cache-max-age: 1h
allowed-algorithms:
  - es256
allowed-clock-skew: 1m
require-exp: true
issuer: https://idp.example.test:8443
verbose-logging: false
distribute:
  to: all

Delete a jwt auth

SecurityaccessToken

Request

path Parameters

jwt-auth-name

required

string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Name of this JWT auth configuration.

query Parameters

validate

string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"

Responses

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

delete/v1/config/strongbox/authentication/jwt/{jwt-auth-name}

Replace or create a new jwt auth

SecurityaccessToken

Request

path Parameters

jwt-auth-name

required

string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Name of this JWT auth configuration.

query Parameters

validate

string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"

Request Body schema:
application/yaml

One of:

discovery-url	string OIDC discovery URL used to fetch the issuer's public keys. The well-known OpenID configuration document is fetched from this URL (appending /.well-known/openid-configuration if not already present), and the JWKS URI is extracted from that document. Common for OIDC providers and GitLab CI/CD.
jwks-ca-cert	string <ca-cert> One or more root certificates in PEM format. CA certificates, in PEM format, to use when validating the TLS connection to the discovery and JWKS endpoints. Multiple certs may be added as one string. By default, the system root CA bundle is used (see jwks-use-root-ca-certs). Configure this leaf when using a private CA. TLS verification can be disabled entirely with jwks-tls-verify false.
jwks-use-root-ca-certs	boolean Default: true Use the system root CA certificate bundle when validating the TLS certificate of the discovery and JWKS endpoints.
jwks-server-name-indication	string Override the TLS SNI hostname used when connecting to the discovery and JWKS endpoints. By default the hostname from discovery-url is used.
jwks-tls-verify	boolean Default: true Verify the TLS certificate of the discovery and JWKS endpoints. Should only be set to false in test environments, never in production.
jwks-refresh-interval	string <duration> Default: "5m" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` How often to refresh the JWKS from the discovery endpoint.
jwks-request-timeout	string <duration> Default: "5s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Timeout for JWKS retrieval.
jwks-cache-max-age	string <duration> Default: "1h" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Max time to use cached keys if JWKS fetch fails.
name	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ Name of this JWT auth configuration.
allowed-algorithms	Array of strings <enumeration> `es256` `es384` `rs256` JOSE algorithms accepted for signatures, e.g. 'es256', 'es384', 'rs256'. The default set is: 'es256', 'es384', 'rs256'.
allowed-clock-skew	string <duration> Default: "60s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Allowed clock skew when validating exp/nbf/iat.
require-exp	boolean Default: true Require 'exp' claim.
issuer	string Expected 'iss' claim value. If not set, the 'iss' claim is not validated and any issuer is accepted.
verbose-logging	boolean Default: false Enable verbose logging for JWT authentication attempts. Do not enable in production. The log entries will appear in the volga topic system:logs on the site where the logging occurred.
	to (object) or sites (object) or deployments (object)

Responses

201

Created

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

put/v1/config/strongbox/authentication/jwt/{jwt-auth-name}

Request samples

Payload

name: example
discovery-url: https://idp.example.test:8443
jwks-ca-cert: |
  -----BEGIN CERTIFICATE-----
  MIIB...REPLACE_ME...==
  -----END CERTIFICATE-----
jwks-use-root-ca-certs: false
jwks-server-name-indication: idp.example.test
jwks-tls-verify: true
jwks-refresh-interval: 5m
jwks-request-timeout: 5s
jwks-cache-max-age: 1h
allowed-algorithms:
  - es256
allowed-clock-skew: 1m
require-exp: true
issuer: https://idp.example.test:8443
verbose-logging: false
distribute:
  to: all

Retrieve the configuration of a jwt auth

SecurityaccessToken

Request

path Parameters

jwt-auth-name

required

string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Name of this JWT auth configuration.

query Parameters

fields	string Retrieve only requested fields from the resource See section fields
where	string Retrieve only items matching the given expression. See section where
validate	string <enumeration> Validate the request but do not actually perform the requested operation Value: "true"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/authentication/jwt/{jwt-auth-name}

Response samples

name: example
discovery-url: https://idp.example.test:8443
jwks-ca-cert: |
  -----BEGIN CERTIFICATE-----
  MIIB...REPLACE_ME...==
  -----END CERTIFICATE-----
jwks-use-root-ca-certs: false
jwks-server-name-indication: idp.example.test
jwks-tls-verify: true
jwks-refresh-interval: 5m
jwks-request-timeout: 5s
jwks-cache-max-age: 1h
allowed-algorithms:
  - es256
allowed-clock-skew: 1m
require-exp: true
issuer: https://idp.example.test:8443
verbose-logging: false
distribute:
  to: all

Create a new jwt auth role

SecurityaccessToken

Request

path Parameters

jwt-auth-name

required

string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Name of this JWT auth configuration.

query Parameters

validate

string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"

Request Body schema:
application/yaml

name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
bound-audiences	Array of strings Optionally configured list of 'aud' claims. If configured, at least one entry must match.
user-claim	string Default: "sub" Claim to use as unique user identifier.
bound-subject	string If configured the 'sub' claim must match this value.
	object All entries must be present in the claim and their values must match.
required-claims	Array of strings Claims that must be present in order to allow authentication.
	object Map that describes how claims are mapped into meta attributes in the token. Name of claim as returned by the JWT issuer.
policies-claim	string Name of custom claim to use for assigning policies. The claim is expected to contain an array of policies.
verbose-logging	boolean Default: false Enable verbose logging for JWT authentication attempts on this role. Do not enable in production.
token-ttl	string <duration> A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Initial time-to-live (TTL) for the token On creation, expiry = now + token-ttl (if provided). Actual TTL is capped by: `token-max-ttl` (per-issue ceiling) `token-explicit-max-ttl` (absolute lifetime since creation) `tenant-max-ttl` (tenant system wide) parent token's remaining lifetime (if any) TTL can later be changed by the refresh action, which always resets TTL from the refresh time. If unset, the system default TTL applies.
token-max-ttl	string <duration> A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Maximum TTL allowed at issuance or refresh. Acts as per-operation ceiling. Part of absolute cap: `MaxTTL = min(tenant-max-ttl, token-max-ttl, token-explicit-max-ttl)` If unset, only system and explicit caps apply.
token-policies	Array of strings <name> These policies are associated with the token that results from successful login, in addition to any policies specified in the entity-alias and the entity.
token-auto-bound-cidrs	string <enumeration> Default: "none" enumeration: - `none`: Do not set bound-cidrs automatically. (default) - `host`: Set bound-cidrs to the host address when token is created. - `network`: Set bound-cidrs to the network from where the token was created. The prefix defaults to 24, unless the subnet is specified in the token-bound-cidrs setting, in which case the same network prefix is used as in token-bound-cidrs. Automatically set bound-cidrs of token to the host or network from where the token was created.
token-bound-cidrs	Array of strings <ip-address-and-prefix-length> ipv4-address-and-prefix-length: The ipv4-address-and-prefix-length type represents a combination of an IPv4 address and a prefix length. The prefix length is given by the number following the slash character and must be less than or equal to 32. For example `192.168.131.0/24`. ipv6-address-and-prefix-length: The ipv6-address-and-prefix-length type represents a combination of an IPv6 address and a prefix length. The prefix length is given by the number following the slash character and must be less than or equal to 128. For example `fe80::42:b6ff:feff:2f3/64`. The ip-address-and-prefix-length type represents a combination of an IP address and a prefix length and is IP version neutral. The format of the textual representations implies the IP version. Limit the use of the token to specific subnets. The token will be invalid if the src ip address originates from a subnet not listed in the token-bound-cidrs. All subnets are accepted if the list is empty.
token-explicit-max-ttl	string <duration> Default: "0s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Absolute lifetime cap since creation. Token cannot outlive `creation-time + token-explicit-max-ttl`. Overrides `token-ttl` and `token-max-ttl` when necessary. Part of MaxTTL. `0s` = disabled (tenant-max-ttl still applies).
token-no-default-policy	boolean Default: false Do not add the `default` policy to the token if this is set to `true`.
token-num-uses	integer <uint32> Default: 0 Limit the number of times the token can be used.
token-period	string <duration> Default: "0s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Periodic token setting. If > 0, token is periodic. On refresh a NEW TTL is set: `new-ttl = min(token-period, token-max-ttl, MaxTTL, parent-remaining)` Periodic tokens can live indefinitely if refreshed before expiry, unless capped by explicit-max-ttl, or parent expiry. Requires `token-renewable = true`. Initial issuance: defaults to token-period if ttl not set (subject to caps).
token-type	string <token-type> Default: "default" `service`: Long-lived token intended for machine-to-machine use. Not subject to periodic renewal requirements. `default`: Standard interactive or short-lived token with normal TTL and renewal semantics. Distinguishes service tokens (machine-to-machine, long-lived) from default tokens (interactive or short-lived).
token-renewable	boolean Default: true Controls if refresh is allowed `true`: token can be refreshed. `false`: refresh requests are rejected, even if periodic.
	object If present and a jwt-signing-key has been configured in spiffe-settings, then a jwt-svid will be issued in addition to the normal token. The TTL will be the same as for the token.
	object If present and an issuing-ca has been configured in the spiffe-settings, then a x509-svid will be returned in addition to the normal token

Responses

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict (instance exists)

503

Service Unavailable (strongbox sealed)

post/v1/config/strongbox/authentication/jwt/{jwt-auth-name}/roles

Request samples

Payload

name: default
bound-audiences:
  - myapp
user-claim: sub
bound-subject: user@example.com
bound-claims:
  env: production
required-claims:
  - email
claim-mappings:
  email: email
  sub: username
policies-claim: policies
verbose-logging: false
token-ttl: 1d
token-max-ttl: 30d
token-policies:
  - user
token-auto-bound-cidrs: host
token-bound-cidrs:
  - 192.168.1.0/24
token-explicit-max-ttl: 0s
token-no-default-policy: false
token-num-uses: 0
token-period: 0s
token-type: default
token-renewable: true
token-spiffe-jwt:
  jwt-audiences:
    - popcorn
token-spiffe-x509:
  cert-type: client
  server-ext-usage: false
  client-ext-usage: true
  code-signing-ext-usage: false
  full-authority-key-identifier: false

Retrieve the configuration of all jwt auth roles

SecurityaccessToken

Request

path Parameters

jwt-auth-name

required

string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Name of this JWT auth configuration.

query Parameters

fields	string Retrieve only requested fields from the resource See section fields
where	string Retrieve only items matching the given expression. See section where
validate	string <enumeration> Validate the request but do not actually perform the requested operation Value: "true"
keys	string <enumeration> Retrieve only the keys for the list Value: "true"
count	string <enumeration> Retrieve only the number of elements in the list Value: "true"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/authentication/jwt/{jwt-auth-name}/roles

Response samples

- name: default
  bound-audiences:
    - myapp
  user-claim: sub
  bound-subject: user@example.com
  bound-claims:
    env: production
  required-claims:
    - email
  claim-mappings:
    email: email
    sub: username
  policies-claim: policies
  verbose-logging: false
  token-ttl: 1d
  token-max-ttl: 30d
  token-policies:
    - user
  token-auto-bound-cidrs: host
  token-bound-cidrs:
    - 192.168.1.0/24
  token-explicit-max-ttl: 0s
  token-no-default-policy: false
  token-num-uses: 0
  token-period: 0s
  token-type: default
  token-renewable: true
  token-spiffe-jwt:
    jwt-audiences:
      - popcorn
  token-spiffe-x509:
    cert-type: client
    server-ext-usage: false
    client-ext-usage: true
    code-signing-ext-usage: false
    full-authority-key-identifier: false

Update a jwt auth role

SecurityaccessToken

Request

path Parameters

jwt-auth-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ Name of this JWT auth configuration.
jwt-auth-role-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ name of jwt-auth-role

query Parameters

validate

string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"

Request Body schema:
application/yaml

name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
bound-audiences	Array of strings Optionally configured list of 'aud' claims. If configured, at least one entry must match.
user-claim	string Default: "sub" Claim to use as unique user identifier.
bound-subject	string If configured the 'sub' claim must match this value.
	object All entries must be present in the claim and their values must match.
required-claims	Array of strings Claims that must be present in order to allow authentication.
	object Map that describes how claims are mapped into meta attributes in the token. Name of claim as returned by the JWT issuer.
policies-claim	string Name of custom claim to use for assigning policies. The claim is expected to contain an array of policies.
verbose-logging	boolean Default: false Enable verbose logging for JWT authentication attempts on this role. Do not enable in production.
token-ttl	string <duration> A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Initial time-to-live (TTL) for the token On creation, expiry = now + token-ttl (if provided). Actual TTL is capped by: `token-max-ttl` (per-issue ceiling) `token-explicit-max-ttl` (absolute lifetime since creation) `tenant-max-ttl` (tenant system wide) parent token's remaining lifetime (if any) TTL can later be changed by the refresh action, which always resets TTL from the refresh time. If unset, the system default TTL applies.
token-max-ttl	string <duration> A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Maximum TTL allowed at issuance or refresh. Acts as per-operation ceiling. Part of absolute cap: `MaxTTL = min(tenant-max-ttl, token-max-ttl, token-explicit-max-ttl)` If unset, only system and explicit caps apply.
token-policies	Array of strings <name> These policies are associated with the token that results from successful login, in addition to any policies specified in the entity-alias and the entity.
token-auto-bound-cidrs	string <enumeration> Default: "none" enumeration: - `none`: Do not set bound-cidrs automatically. (default) - `host`: Set bound-cidrs to the host address when token is created. - `network`: Set bound-cidrs to the network from where the token was created. The prefix defaults to 24, unless the subnet is specified in the token-bound-cidrs setting, in which case the same network prefix is used as in token-bound-cidrs. Automatically set bound-cidrs of token to the host or network from where the token was created.
token-bound-cidrs	Array of strings <ip-address-and-prefix-length> ipv4-address-and-prefix-length: The ipv4-address-and-prefix-length type represents a combination of an IPv4 address and a prefix length. The prefix length is given by the number following the slash character and must be less than or equal to 32. For example `192.168.131.0/24`. ipv6-address-and-prefix-length: The ipv6-address-and-prefix-length type represents a combination of an IPv6 address and a prefix length. The prefix length is given by the number following the slash character and must be less than or equal to 128. For example `fe80::42:b6ff:feff:2f3/64`. The ip-address-and-prefix-length type represents a combination of an IP address and a prefix length and is IP version neutral. The format of the textual representations implies the IP version. Limit the use of the token to specific subnets. The token will be invalid if the src ip address originates from a subnet not listed in the token-bound-cidrs. All subnets are accepted if the list is empty.
token-explicit-max-ttl	string <duration> Default: "0s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Absolute lifetime cap since creation. Token cannot outlive `creation-time + token-explicit-max-ttl`. Overrides `token-ttl` and `token-max-ttl` when necessary. Part of MaxTTL. `0s` = disabled (tenant-max-ttl still applies).
token-no-default-policy	boolean Default: false Do not add the `default` policy to the token if this is set to `true`.
token-num-uses	integer <uint32> Default: 0 Limit the number of times the token can be used.
token-period	string <duration> Default: "0s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Periodic token setting. If > 0, token is periodic. On refresh a NEW TTL is set: `new-ttl = min(token-period, token-max-ttl, MaxTTL, parent-remaining)` Periodic tokens can live indefinitely if refreshed before expiry, unless capped by explicit-max-ttl, or parent expiry. Requires `token-renewable = true`. Initial issuance: defaults to token-period if ttl not set (subject to caps).
token-type	string <token-type> Default: "default" `service`: Long-lived token intended for machine-to-machine use. Not subject to periodic renewal requirements. `default`: Standard interactive or short-lived token with normal TTL and renewal semantics. Distinguishes service tokens (machine-to-machine, long-lived) from default tokens (interactive or short-lived).
token-renewable	boolean Default: true Controls if refresh is allowed `true`: token can be refreshed. `false`: refresh requests are rejected, even if periodic.
	object If present and a jwt-signing-key has been configured in spiffe-settings, then a jwt-svid will be issued in addition to the normal token. The TTL will be the same as for the token.
	object If present and an issuing-ca has been configured in the spiffe-settings, then a x509-svid will be returned in addition to the normal token

Responses

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

patch/v1/config/strongbox/authentication/jwt/{jwt-auth-name}/roles/{jwt-auth-role-name}

Request samples

Payload

name: default
bound-audiences:
  - myapp
user-claim: sub
bound-subject: user@example.com
bound-claims:
  env: production
required-claims:
  - email
claim-mappings:
  email: email
  sub: username
policies-claim: policies
verbose-logging: false
token-ttl: 1d
token-max-ttl: 30d
token-policies:
  - user
token-auto-bound-cidrs: host
token-bound-cidrs:
  - 192.168.1.0/24
token-explicit-max-ttl: 0s
token-no-default-policy: false
token-num-uses: 0
token-period: 0s
token-type: default
token-renewable: true
token-spiffe-jwt:
  jwt-audiences:
    - popcorn
token-spiffe-x509:
  cert-type: client
  server-ext-usage: false
  client-ext-usage: true
  code-signing-ext-usage: false
  full-authority-key-identifier: false

Delete a jwt auth role

SecurityaccessToken

Request

path Parameters

jwt-auth-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ Name of this JWT auth configuration.
jwt-auth-role-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ name of jwt-auth-role

query Parameters

validate

string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"

Responses

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

delete/v1/config/strongbox/authentication/jwt/{jwt-auth-name}/roles/{jwt-auth-role-name}

Replace or create a new jwt auth role

SecurityaccessToken

Request

path Parameters

jwt-auth-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ Name of this JWT auth configuration.
jwt-auth-role-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ name of jwt-auth-role

query Parameters

validate

string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"

Request Body schema:
application/yaml

name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
bound-audiences	Array of strings Optionally configured list of 'aud' claims. If configured, at least one entry must match.
user-claim	string Default: "sub" Claim to use as unique user identifier.
bound-subject	string If configured the 'sub' claim must match this value.
	object All entries must be present in the claim and their values must match.
required-claims	Array of strings Claims that must be present in order to allow authentication.
	object Map that describes how claims are mapped into meta attributes in the token. Name of claim as returned by the JWT issuer.
policies-claim	string Name of custom claim to use for assigning policies. The claim is expected to contain an array of policies.
verbose-logging	boolean Default: false Enable verbose logging for JWT authentication attempts on this role. Do not enable in production.
token-ttl	string <duration> A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Initial time-to-live (TTL) for the token On creation, expiry = now + token-ttl (if provided). Actual TTL is capped by: `token-max-ttl` (per-issue ceiling) `token-explicit-max-ttl` (absolute lifetime since creation) `tenant-max-ttl` (tenant system wide) parent token's remaining lifetime (if any) TTL can later be changed by the refresh action, which always resets TTL from the refresh time. If unset, the system default TTL applies.
token-max-ttl	string <duration> A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Maximum TTL allowed at issuance or refresh. Acts as per-operation ceiling. Part of absolute cap: `MaxTTL = min(tenant-max-ttl, token-max-ttl, token-explicit-max-ttl)` If unset, only system and explicit caps apply.
token-policies	Array of strings <name> These policies are associated with the token that results from successful login, in addition to any policies specified in the entity-alias and the entity.
token-auto-bound-cidrs	string <enumeration> Default: "none" enumeration: - `none`: Do not set bound-cidrs automatically. (default) - `host`: Set bound-cidrs to the host address when token is created. - `network`: Set bound-cidrs to the network from where the token was created. The prefix defaults to 24, unless the subnet is specified in the token-bound-cidrs setting, in which case the same network prefix is used as in token-bound-cidrs. Automatically set bound-cidrs of token to the host or network from where the token was created.
token-bound-cidrs	Array of strings <ip-address-and-prefix-length> ipv4-address-and-prefix-length: The ipv4-address-and-prefix-length type represents a combination of an IPv4 address and a prefix length. The prefix length is given by the number following the slash character and must be less than or equal to 32. For example `192.168.131.0/24`. ipv6-address-and-prefix-length: The ipv6-address-and-prefix-length type represents a combination of an IPv6 address and a prefix length. The prefix length is given by the number following the slash character and must be less than or equal to 128. For example `fe80::42:b6ff:feff:2f3/64`. The ip-address-and-prefix-length type represents a combination of an IP address and a prefix length and is IP version neutral. The format of the textual representations implies the IP version. Limit the use of the token to specific subnets. The token will be invalid if the src ip address originates from a subnet not listed in the token-bound-cidrs. All subnets are accepted if the list is empty.
token-explicit-max-ttl	string <duration> Default: "0s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Absolute lifetime cap since creation. Token cannot outlive `creation-time + token-explicit-max-ttl`. Overrides `token-ttl` and `token-max-ttl` when necessary. Part of MaxTTL. `0s` = disabled (tenant-max-ttl still applies).
token-no-default-policy	boolean Default: false Do not add the `default` policy to the token if this is set to `true`.
token-num-uses	integer <uint32> Default: 0 Limit the number of times the token can be used.
token-period	string <duration> Default: "0s" A duration in years, days, hours, minutes and seconds. Format is `[<digits>y][<digits>d][<digits>m][<digits>s]`. Examples: `1y2d5h`, `5h` or `10m30s` Periodic token setting. If > 0, token is periodic. On refresh a NEW TTL is set: `new-ttl = min(token-period, token-max-ttl, MaxTTL, parent-remaining)` Periodic tokens can live indefinitely if refreshed before expiry, unless capped by explicit-max-ttl, or parent expiry. Requires `token-renewable = true`. Initial issuance: defaults to token-period if ttl not set (subject to caps).
token-type	string <token-type> Default: "default" `service`: Long-lived token intended for machine-to-machine use. Not subject to periodic renewal requirements. `default`: Standard interactive or short-lived token with normal TTL and renewal semantics. Distinguishes service tokens (machine-to-machine, long-lived) from default tokens (interactive or short-lived).
token-renewable	boolean Default: true Controls if refresh is allowed `true`: token can be refreshed. `false`: refresh requests are rejected, even if periodic.
	object If present and a jwt-signing-key has been configured in spiffe-settings, then a jwt-svid will be issued in addition to the normal token. The TTL will be the same as for the token.
	object If present and an issuing-ca has been configured in the spiffe-settings, then a x509-svid will be returned in addition to the normal token

Responses

201

Created

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

put/v1/config/strongbox/authentication/jwt/{jwt-auth-name}/roles/{jwt-auth-role-name}

Request samples

Payload

name: default
bound-audiences:
  - myapp
user-claim: sub
bound-subject: user@example.com
bound-claims:
  env: production
required-claims:
  - email
claim-mappings:
  email: email
  sub: username
policies-claim: policies
verbose-logging: false
token-ttl: 1d
token-max-ttl: 30d
token-policies:
  - user
token-auto-bound-cidrs: host
token-bound-cidrs:
  - 192.168.1.0/24
token-explicit-max-ttl: 0s
token-no-default-policy: false
token-num-uses: 0
token-period: 0s
token-type: default
token-renewable: true
token-spiffe-jwt:
  jwt-audiences:
    - popcorn
token-spiffe-x509:
  cert-type: client
  server-ext-usage: false
  client-ext-usage: true
  code-signing-ext-usage: false
  full-authority-key-identifier: false

Retrieve the configuration of a jwt auth role

SecurityaccessToken

Request

path Parameters

jwt-auth-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ Name of this JWT auth configuration.
jwt-auth-role-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ name of jwt-auth-role

query Parameters

fields	string Retrieve only requested fields from the resource See section fields
where	string Retrieve only items matching the given expression. See section where
validate	string <enumeration> Validate the request but do not actually perform the requested operation Value: "true"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/authentication/jwt/{jwt-auth-name}/roles/{jwt-auth-role-name}

Response samples

name: default
bound-audiences:
  - myapp
user-claim: sub
bound-subject: user@example.com
bound-claims:
  env: production
required-claims:
  - email
claim-mappings:
  email: email
  sub: username
policies-claim: policies
verbose-logging: false
token-ttl: 1d
token-max-ttl: 30d
token-policies:
  - user
token-auto-bound-cidrs: host
token-bound-cidrs:
  - 192.168.1.0/24
token-explicit-max-ttl: 0s
token-no-default-policy: false
token-num-uses: 0
token-period: 0s
token-type: default
token-renewable: true
token-spiffe-jwt:
  jwt-audiences:
    - popcorn
token-spiffe-x509:
  cert-type: client
  server-ext-usage: false
  client-ext-usage: true
  code-signing-ext-usage: false
  full-authority-key-identifier: false

Retrieve the state of all jwt auths

SecurityaccessToken

Request

query Parameters

fields	string Retrieve only requested fields from the resource See section fields
where	string Retrieve only items matching the given expression. See section where
site	string Send the request to the specfifed site
content	string <enumeration> Filter descendant nodes in the response Enum: "config" "nonconfig"
keys	string <enumeration> Retrieve only the keys for the list Value: "true"
count	string <enumeration> Retrieve only the number of elements in the list Value: "true"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/authentication/jwt

Response samples

- name: example
  discovery-url: https://idp.example.test:8443
  jwks-ca-cert: |
    -----BEGIN CERTIFICATE-----
    MIIB...REPLACE_ME...==
    -----END CERTIFICATE-----
  jwks-use-root-ca-certs: false
  jwks-server-name-indication: idp.example.test
  jwks-tls-verify: true
  jwks-refresh-interval: 5m
  jwks-request-timeout: 5s
  jwks-cache-max-age: 1h
  allowed-algorithms:
    - es256
  allowed-clock-skew: 1m
  require-exp: true
  issuer: https://idp.example.test:8443
  verbose-logging: false
  distribute:
    to: all
  distribution-status:
    to: all

Retrieve the state of a jwt auth

SecurityaccessToken

Request

path Parameters

jwt-auth-name

required

string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Name of this JWT auth configuration.

query Parameters

fields	string Retrieve only requested fields from the resource See section fields
where	string Retrieve only items matching the given expression. See section where
site	string Send the request to the specfifed site
content	string <enumeration> Filter descendant nodes in the response Enum: "config" "nonconfig"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/authentication/jwt/{jwt-auth-name}

Response samples

name: example
discovery-url: https://idp.example.test:8443
jwks-ca-cert: |
  -----BEGIN CERTIFICATE-----
  MIIB...REPLACE_ME...==
  -----END CERTIFICATE-----
jwks-use-root-ca-certs: false
jwks-server-name-indication: idp.example.test
jwks-tls-verify: true
jwks-refresh-interval: 5m
jwks-request-timeout: 5s
jwks-cache-max-age: 1h
allowed-algorithms:
  - es256
allowed-clock-skew: 1m
require-exp: true
issuer: https://idp.example.test:8443
verbose-logging: false
distribute:
  to: all
distribution-status:
  to: all

Retrieve the state of all jwt auth roles

SecurityaccessToken

Request

path Parameters

jwt-auth-name

required

string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Name of this JWT auth configuration.

query Parameters

fields	string Retrieve only requested fields from the resource See section fields
where	string Retrieve only items matching the given expression. See section where
site	string Send the request to the specfifed site
content	string <enumeration> Filter descendant nodes in the response Enum: "config" "nonconfig"
keys	string <enumeration> Retrieve only the keys for the list Value: "true"
count	string <enumeration> Retrieve only the number of elements in the list Value: "true"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/authentication/jwt/{jwt-auth-name}/roles

Response samples

- name: default
  bound-audiences:
    - myapp
  user-claim: sub
  bound-subject: user@example.com
  bound-claims:
    env: production
  required-claims:
    - email
  claim-mappings:
    email: email
    sub: username
  policies-claim: policies
  verbose-logging: false
  token-ttl: 1d
  token-max-ttl: 30d
  token-policies:
    - user
  token-auto-bound-cidrs: host
  token-bound-cidrs:
    - 192.168.1.0/24
  token-explicit-max-ttl: 0s
  token-no-default-policy: false
  token-num-uses: 0
  token-period: 0s
  token-type: default
  token-renewable: true
  token-spiffe-jwt:
    jwt-audiences:
      - popcorn
  token-spiffe-x509:
    cert-type: client
    server-ext-usage: false
    client-ext-usage: true
    code-signing-ext-usage: false
    full-authority-key-identifier: false

Retrieve the state of a jwt auth role

SecurityaccessToken

Request

path Parameters

jwt-auth-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ Name of this JWT auth configuration.
jwt-auth-role-name required	string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ name of jwt-auth-role

query Parameters

fields	string Retrieve only requested fields from the resource See section fields
where	string Retrieve only items matching the given expression. See section where
site	string Send the request to the specfifed site
content	string <enumeration> Filter descendant nodes in the response Enum: "config" "nonconfig"

Responses

200

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/authentication/jwt/{jwt-auth-name}/roles/{jwt-auth-role-name}

Response samples

name: default
bound-audiences:
  - myapp
user-claim: sub
bound-subject: user@example.com
bound-claims:
  env: production
required-claims:
  - email
claim-mappings:
  email: email
  sub: username
policies-claim: policies
verbose-logging: false
token-ttl: 1d
token-max-ttl: 30d
token-policies:
  - user
token-auto-bound-cidrs: host
token-bound-cidrs:
  - 192.168.1.0/24
token-explicit-max-ttl: 0s
token-no-default-policy: false
token-num-uses: 0
token-period: 0s
token-type: default
token-renewable: true
token-spiffe-jwt:
  jwt-audiences:
    - popcorn
token-spiffe-x509:
  cert-type: client
  server-ext-usage: false
  client-ext-usage: true
  code-signing-ext-usage: false
  full-authority-key-identifier: false

➔ Next to Kubernetes Authentication

JWT Authentication

Create a new jwt auth

query Parameters

Request Body schema: application/yamlapplication/jsonapplication/yaml

Retrieve the configuration of all jwt auths

query Parameters

Update a jwt auth

path Parameters

query Parameters

Request Body schema: application/yamlapplication/jsonapplication/yaml

Delete a jwt auth

path Parameters

query Parameters

Replace or create a new jwt auth

path Parameters

query Parameters

Request Body schema: application/yamlapplication/jsonapplication/yaml

Retrieve the configuration of a jwt auth

path Parameters

query Parameters

Create a new jwt auth role

path Parameters

query Parameters

Request Body schema: application/yamlapplication/jsonapplication/yaml

Retrieve the configuration of all jwt auth roles

path Parameters

query Parameters

Update a jwt auth role

path Parameters

query Parameters

Request Body schema: application/yamlapplication/jsonapplication/yaml

Delete a jwt auth role

path Parameters

query Parameters

Replace or create a new jwt auth role

path Parameters

query Parameters

Request Body schema: application/yamlapplication/jsonapplication/yaml

Retrieve the configuration of a jwt auth role

path Parameters

query Parameters

Retrieve the state of all jwt auths

query Parameters

Retrieve the state of a jwt auth

path Parameters

query Parameters

Retrieve the state of all jwt auth roles

path Parameters

query Parameters

Retrieve the state of a jwt auth role

path Parameters

query Parameters

Request Body schema:
application/yaml

Request Body schema:
application/yaml

Request Body schema:
application/yaml

Request Body schema:
application/yaml

Request Body schema:
application/yaml

Request Body schema:
application/yaml