Serve

warning

This feature is experimental.

An X509 SVID or a JWT SVID may be served at any time via the Developer Identity Workload API, but not both simultaneously.

SVID certificates/bundles are not refreshed. The command will terminate upon certificate expiry.

SPIRL Developer Identity allows developers to serve a Workload API locally for development and integration purposes. See fetch for a file-based variant.

Serve X509 SVIDs

By default, spirlctl will serve an X509 SVID over a local SPIFFE Workload API with Envoy SDS support:

spirlctl exp dev-id serve --trust-domain my-trust-domain

You can specify custom parameters to control where the socket becomes available and the redirection address during the authentication challenge.

[...]
  --redirect-addr http://127.0.0.1:54321/auth/callback \
  --spiffe-endpoint-socket unix:/tmp/spirl/devid/workload.sock

Once the Workload API is running you can for example use spirldbg to connect to the socket.

spirldbg svid-x509 --spiffe-endpoint-socket /tmp/spirl/devid/workload.sock

Envoy support

As the serve command also serves the Envoy SDS API you can connect it to a local Envoy.

  clusters:
  - name: spirlctl
    connect_timeout: 1s
    http2_protocol_options: {}
    load_assignment:
      cluster_name: spirlctl
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              pipe:
                path: /tmp/spirl/devid/workload.sock
  - name: your_resource
    transport_socket:
      name: envoy.transport_sockets.tls
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
        common_tls_context:
          tls_params:
            tls_maximum_protocol_version: TLSv1_2
          tls_certificate_sds_secret_configs:
          - name: "default"
            sds_config:
              api_config_source:
                api_type: GRPC
                grpc_services:
                  envoy_grpc:
                    cluster_name: spirlctl
                transport_api_version: V3
              resource_api_version: V3
          combined_validation_context:
            default_validation_context:
              match_subject_alt_names:
                exact: "<PEER SPIFFE ID>"
            validation_context_sds_secret_config:
              name: "ROOTCA"
              sds_config:
                api_config_source:
                  api_type: GRPC
                  grpc_services:
                    envoy_grpc:
                      cluster_name: spirlctl
                  transport_api_version: V3
                resource_api_version: V3

info

The SDS resource names are the following

SPIFFE Resource	SDS Resource Name
X509-SVID	"default"
X509 Bundle	"ROOTCA"

Other SDS resource names are not supported.

Serve JWT SVIDs

By adding the --jwt parameter, you can instead serve a JWT SVID over the Workload API:

spirlctl exp dev-id serve --trust-domain my-trust-domain --jwt

By default the JWT will be issued with an audience of example.com, but you may optionally specify a custom audience using the --audience parameter, which may be provided multiple times:

spirlctl exp dev-id serve --trust-domain my-trust-domain --jwt --audience foo --audience bar

The audience can only be set when first running the spirlctl exp dev-id serve command, and you must terminate and restart the API if you wish to issue SVIDs with a new audience. Any requests to the FetchJWTSVID API for a different audience will error.