SPIRE

https://github.com/spiffe/spire
Admin
SPIRE is a toolchain of APIs for establishing trust between software systems across a wide variety...
Tokens:670,325
Snippets:4,198
Trust Score:9
License:Apache-2.0
Update:4 days ago
Show doc for...
Tokens:
Raw
### PostgreSQL connection string example

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_datastore_sql.md

Example connection string for PostgreSQL, showing space-separated options such as dbname, user, password, host, and sslmode.

```hcl
connection_string = "dbname=postgres user=postgres password=password host=localhost sslmode=disable"
```

--------------------------------

### Run SPIRE Server Windows service (sc.exe start)

Source: https://github.com/spiffe/spire/blob/main/doc/spire_server.md

Starts the SPIRE Server Windows service, passing the run command and configuration file path as service arguments.

```bash
> sc.exe start spire-server run -config c:\spire\conf\server\server.conf
```

--------------------------------

### Start SPIRE Agent Windows service with sc.exe start

Source: https://github.com/spiffe/spire/blob/main/doc/spire_agent.md

Starts the SPIRE Agent Windows service. All arguments to execute SPIRE Agent with the run command must be passed as service arguments, as shown with -config.

```bash
> sc.exe start spire-agent run -config c:\spire\conf\agent\agent.conf
```

--------------------------------

### Example 1a: Allow clause using check_entry_create_namespace

Source: https://github.com/spiffe/spire/blob/main/doc/authorization_policy_engine.md

Example allow clause that sets allow to true when check_entry_create_namespace succeeds. Note that this must be integrated with the rest of the rego policy.

```rego
# Any allow check
allow = true {
    check_entry_create_namespace
}
```

--------------------------------

### server.conf example for sshpop NodeAttestor

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_nodeattestor_sshpop.md

Example server configuration for the sshpop plugin, including trusted CAs, optional canonical_domain, agent_path_template, and verify_client_ip settings.

```hcl
    NodeAttestor "sshpop" {
        plugin_data {
            cert_authorities = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEAWPAsKJ/qMYUIBeH7BLMRCE/bkUvMHX+7OZhANk45S"]
            cert_authorities_path = "./conf/server/dummy_ssh_cert_authority.pub"
            
            # Sensibly check the FQDN set in the certificate principals.
            # canonical_domain = "example.com"

            # Change the agent's SPIFFE ID format
            # agent_path_template = "/{{ .PluginName }}/static/{{ index .ValidPrincipals 0 }}"

            # Optional: when true, require and enforce the source-address critical option
            # verify_client_ip = true
        }
    }
```

--------------------------------

### Create entry with docker:label selector

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_docker.md

Creates a registration entry using a docker:label selector for a container started with 'docker run --label com.example.name=foo [...]'.

```shell
$ spire-server entry create \
    -parentID spiffe://example.org/host \
    -spiffeID spiffe://example.org/host/foo \
    -selector docker:label:com.example.name:foo
```

--------------------------------

### Ensure Metric Label Existence is Constant (Counter Example)

Source: https://github.com/spiffe/spire/blob/main/CONTRIBUTING.md

Shows a counter example where a metric label is added conditionally, which is discouraged because label existence must be constant for all instances of a metric.

```go
var callCounter telemetry.CallCounter
...
if caller != "" {
  callCounter.AddLabel(telemetry.CallerID, caller)
}
...
if x > 5000 {
  callCounter.AddLabel("big_load", "true")
}
```

--------------------------------

### Manual test suite execution commands

Source: https://github.com/spiffe/spire/blob/main/test/integration/suites/key-manager-kmip/README.md

Bash commands to run the integration suite manually: setup Kind cluster, setup KMS, deploy SPIRE and verify authentication, then teardown.

```bash
./00-setup-kind
./01-setup-kms
./02-deploy-spire-and-verify-auth
./teardown
```

--------------------------------

### Start SPIRE Agent with Join Token

Source: https://github.com/spiffe/spire/blob/main/doc/SPIRE101.md

Starts the SPIRE Agent as a background process using a generated join token. Replace <generated-join-token> with the saved value from step #8.

```shell
(in dev shell) # ./bin/spire-agent run -joinToken <generated-join-token> &
```

--------------------------------

### http_challenge agent configuration with proxy

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_nodeattestor_http_challenge.md

Example configuration for using a proxy, setting port to 8080 and advertised_port to 80.

```hcl
    NodeAttestor "http_challenge" {
        plugin_data {
            port = 8080
            advertised_port = 80
        }
    }
```

--------------------------------

### SPIRE Server federation configuration example

Source: https://github.com/spiffe/spire/blob/main/doc/spire_server.md

Example HCL configuration for the federation section, setting up a bundle endpoint server with ACME and defining two federated trust domains with different bundle endpoint profiles.

```hcl
server {
    .
    .
    .
    federation {
        bundle_endpoint {
            address = "0.0.0.0"
            port = 8443
            refresh_hint = "10m"
            profile "https_web" {
                acme {
                    domain_name = "example.org"
                    email = "mail@example.org"
                }
            }
        }
        federates_with "domain1.test" {
            bundle_endpoint_url = "https://1.2.3.4:8443"
            bundle_endpoint_profile "https_web" {}
        }
        federates_with "domain2.test" {
            bundle_endpoint_url = "https://5.6.7.8:8443"
            bundle_endpoint_profile "https_spiffe" {
                endpoint_spiffe_id = "spiffe://domain2.test/beserver"
            }
            bootstrap_bundle_path = "/etc/spire/domain2.pem"
        }
    }
}
```

--------------------------------

### Basic Kubernetes RBAC and ConfigMap for SPIRE Server Notifier

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_notifier_k8sbundle.md

YAML manifests for a basic setup: a ClusterRole granting get and patch on configmaps, a ClusterRoleBinding for the spire-server service account, and a ConfigMap named spire-bundle. The ClusterRoleBinding binds the ClusterRole to the service account in the spire namespace.

```yaml
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: spire-server-cluster-role
rules:
- apiGroups: [""]
  resources: ["configmaps"]
  verbs: ["get", "patch"]

---

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: spire-server-cluster-role-binding
subjects:
- kind: ServiceAccount
  name: spire-server
  namespace: spire
roleRef:
  kind: ClusterRole
  name: spire-server-cluster-role
  apiGroup: rbac.authorization.k8s.io

---

apiVersion: v1
kind: ConfigMap
metadata:
  name: spire-bundle
  namespace: spire

```

--------------------------------

### Rootless Podman customization example (HCL)

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_docker.md

Example HCL configuration for the docker WorkloadAttestor that enables rootless Podman support and customizes the Podman socket path template. When use_rootless_podman is true, SPIRE calls the Podman API using podman_socket_path_template with <uid> substituted into %d. This is opt-in because rootless Podman workloads can present arbitrary container labels for their own UID.

```hcl
WorkloadAttestor "docker" {
    plugin_data {
        use_rootless_podman = true
        podman_socket_path_template = "unix:///custom/user/%d/podman.sock"
    }
}
```

--------------------------------

### Start the SPIRE Server as a background process

Source: https://github.com/spiffe/spire/blob/main/doc/SPIRE101.md

Runs the SPIRE Server in the background.

```shell
(in dev shell) # ./bin/spire-server run &
```

--------------------------------

### Kubernetes RBAC and ConfigMap example for spire-server

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_bundlepublisher_k8s_configmap.md

Defines a Role with permissions to create, get, and patch the 'spire-bundle' ConfigMap, a RoleBinding to bind that Role to the 'spire-server' ServiceAccount, and the ConfigMap itself. The Role is namespace-scoped and restricts operations to the specific ConfigMap name. The Apply operation uses Server-Side Apply with field manager 'spire-bundlepublisher-k8s_configmap'.

```yaml
kind: Role # Note: Using Role instead of ClusterRole for namespace-scoped permissions
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: spire-server-role
  namespace: spire
rules:
- apiGroups: [""]
  resources: ["configmaps"]
  verbs: ["create", "get", "patch"]
  resourceNames: ["spire-bundle"]  # Restrict to specific ConfigMap for create, get and patch operations

---

kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: spire-server-role-binding
  namespace: spire
subjects:
- kind: ServiceAccount
  name: spire-server
  namespace: spire
roleRef:
  kind: Role
  name: spire-server-role
  apiGroup: rbac.authorization.k8s.io

---

apiVersion: v1
kind: ConfigMap
metadata:
  name: spire-bundle
  namespace: spire

```

--------------------------------

### Example MySQL connection_string in HCL

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_datastore_sql.md

Example of a MySQL connection_string using TCP protocol and parseTime=true. Consult the MySQL driver repository for more options.

```hcl
connection_string = "username:password@tcp(localhost:3306)/dbname?parseTime=true"
```

--------------------------------

### Sample configuration for tpm_devid server plugin

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_nodeattestor_tpm_devid.md

Example HCL configuration for the tpm_devid NodeAttestor plugin. It sets the paths to the DevID CA and endorsement CA certificates.

```hcl
    NodeAttestor "tpm_devid" {
        plugin_data {
            devid_ca_path = "/opt/spire/conf/server/devid-cacert.pem"
            endorsement_ca_path = "/opt/spire/conf/server/endorsement-cacert.pem"
        }
    }
```

--------------------------------

### Sample HCL configuration for x509pop agent plugin

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_nodeattestor_x509pop.md

Example configuration for the x509pop agent plugin, specifying the private key and certificate paths. The certificate file must contain the identity certificate followed by any intermediates.

```hcl
    NodeAttestor "x509pop" {
        plugin_data {
            private_key_path = "/opt/spire/conf/agent/agent.key.pem"
            certificate_path = "/opt/spire/conf/agent/agent.crt.pem"
        }
    }
```

--------------------------------

### Install tpm2-tools and tpm2-openssl

Source: https://github.com/spiffe/spire/blob/main/doc/tpm_deployment_walkthrough.md

Installs the required provisioning tooling on Debian/Ubuntu or Fedora/RHEL. The tpm2-openssl package provides the OpenSSL tpm2 provider used to generate the CSR.

```shell
# Debian/Ubuntu
apt-get install -y tpm2-tools tpm2-openssl
```

```shell
# Fedora/RHEL
dnf install -y tpm2-tools tpm2-openssl
```

--------------------------------

### Sample HCL configuration for gcp_secretmanager

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_svidstore_gcp_secretmanager.md

Example configuration for the plugin, showing the optional service_account_file setting. If omitted, credentials are retrieved from the GOOGLE_APPLICATION_CREDENTIALS environment variable.

```hcl
    SVIDStore "gcp_secretmanager" {
       plugin_data {
           service_account_file = "/opt/token"
       }
    }
```

--------------------------------

### Avoid Duplicate Metric Labels (Counter Example)

Source: https://github.com/spiffe/spire/blob/main/CONTRIBUTING.md

Shows two counter examples of adding the same label name multiple times to a metric, which is discouraged because it makes metrics less usable for non-tagging libraries like statsd.

```go
[]telemetry.Label{
  {Name: "someName", "val1"},
  {Name: "someName", "val2"},
}
```

```go
var callCounter telemetry.CallCounter
...
callCounter.AddLabel("someName", "val1")
...
callCounter.AddLabel("someName", "val2")
```

--------------------------------

### Enable broker endpoint with socket_path, bind_address, and brokers list

Source: https://github.com/spiffe/spire/blob/main/doc/spire_agent.md

Add this experimental broker block to the agent configuration. At least one of socket_path (POSIX UDS) or bind_address (TCP) must be set; both may be set. socket_path must not be in the same directory as the Workload API socket or the agent will refuse to start. The brokers list is required and each entry must include allowed_reference_types with at least one object containing type_url. Set allow_over_tcp = true only when the reference type is safe over the network; it defaults to false. Use type_url = "*" to allow any reference type.

```hcl
agent {
    trust_domain = "example.org"
    ...
    experimental {
        broker {
            socket_path  = "/run/spire/broker-sockets/broker.sock"  # POSIX UDS
            bind_address = "0.0.0.0:8443"                           # optional TCP

            brokers = [
                {
                    id = "spiffe://example.org/some/broker"
                    allowed_reference_types = [
                        {
                            type_url = "type.googleapis.com/spiffe.broker.WorkloadPIDReference"
                        },
                        {
                            type_url = "type.googleapis.com/spiffe.broker.KubernetesObjectReference"
                            allow_over_tcp = true
                        },
                    ]
                },
                {
                    id = "spiffe://example.org/wildcard/broker"
                    allowed_reference_types = [
                        {
                            type_url = "*"
                        },
                    ]
                },
            ]
        }
    }
}
```

--------------------------------

### Launch a shell inside the development container

Source: https://github.com/spiffe/spire/blob/main/CONTRIBUTING.md

Run this command after building the dev image to start a shell inside the development container. The container shares the .build cache and $GOPATH/pkg/mod to avoid reinstalling the toolchain and dependencies.

```shell
$ make dev-shell
```

--------------------------------

### Sample configuration for KeyManager disk plugin

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_keymanager_disk.md

HCL configuration block for the disk KeyManager plugin. The directory option sets the path where the private key is stored. This example uses /opt/spire/data/agent.

```hcl
    KeyManager "disk" {
        plugin_data = {
            directory = "/opt/spire/data/agent"
        }
    }
```

--------------------------------

### keys.json content with private keys

Source: https://github.com/spiffe/spire/blob/main/doc/cure53-report.pdf

Example output of the keys.json file containing private keys. The file permissions are incorrectly set to 0644, which is insecure; 0600 should be used instead.

```json
{
"keys": {
"JWT-Signer-A":
"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgnHN6i3MmltAFIunvAfFCGm65d0sxBOt
Xhny6gqf4xQqhRANCAAQ+u3j23JuqxnRHiuWjhuQ1cItJFluxRjTm+HVXENeq6KAX3QgqpxkarVuG+SZ
jS0A0TzoqJHd1M7yMvdD+zR19",
"JWT-Signer-B":
"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgt9/m9kbtMmFmTNSVX1OukhId2B3fBIs
FIKTPs4tUiiqhRANCAAQHP6raGmLbnrIQp5FzRSFTrVSEEbLh3tgXSgIxokHYnb9bVK9mJa+rpUjMw7r
l77w7CWhqRKjEvevBRvhVFPNd",
"x509-CA-A":
"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgRKQFwCWb/cWN2XM0gkz9P9Rt7O7LeG4
2eJ7Tm7x/tgWhRANCAASI/
Pl5gMAxim1iD0tn0ILvkwz7N5JuyqluIvM4MZ050g8bWsus47jtzzbHi6VT6Xp/
yDLM8fmWQtXsrvBOgYyA",
"x509-CA-B":
"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgHtk+zLvKi4gpH1ILq3ywafZ3i/
c4HOez3HV7IoyCwBWhRANCAAQIEDGWWk/HgBDBA1gRcRH01B/
V+pbNdQVp63RrGQ0PQ7P1+Q5ScSD38qs8S2eKmQ1o9/rFdFTjusWqgGF0A/ru"
}
```

--------------------------------

### Allow clause using check_entry_create_admin_flag

Source: https://github.com/spiffe/spire/blob/main/doc/authorization_policy_engine.md

An example allow clause that uses the check_entry_create_admin_flag rule. Note that it is important to check how this fits with other parts of the Rego policy.

```rego
# Any allow check
allow = true {
    check_entry_create_admin_flag
}
```

--------------------------------

### Sample x509pop NodeAttestor HCL configuration

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_nodeattestor_x509pop.md

Example HCL configuration for the x509pop NodeAttestor plugin. It sets ca_bundle_path to the trusted CA bundle and includes commented-out options for agent_path_template, max_intermediates, and max_rsa_key_size with their defaults.

```hcl
    NodeAttestor "x509pop" {
        plugin_data {
            ca_bundle_path = "/opt/spire/conf/server/agent-cacert.pem"

            # Change the agent's SPIFFE ID format
            # agent_path_template = "/{{ .PluginName }}/cn/{{ .Subject.CommonName }}"

            # Optional: Maximum number of intermediate certificates (default: 4)
            # max_intermediates = 4

            # Optional: Maximum RSA key size in bits (default: 8192)
            # max_rsa_key_size = 8192
        }
    }
```

--------------------------------

### xDS bootstrap file JSON

Source: https://github.com/spiffe/spire/blob/main/doc/spire_agent.md

Example bootstrap file pointed to by GRPC_XDS_BOOTSTRAP. It specifies an xDS server with TLS channel credentials and a node identity. The xDS server must be local (unix socket or loopback) or use tls channel credentials to protect the channel.

```json
{
  "xds_servers": [
    {
      "server_uri": "xds.example.org:18000",
      "channel_creds": [
        {
          "type": "tls",
          "config": {
            "ca_certificate_file": "/opt/spire/conf/agent/xds-ca.crt.pem"
          }
        }
      ],
      "server_features": ["xds_v3"]
    }
  ],
  "node": {
    "id": "spire-agent",
    "locality": {
      "region": "dc1",
      "zone": "zone1"
    }
  }
}
```

--------------------------------

### IAM Policy binding YAML example

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_svidstore_gcp_secretmanager.md

Shows the YAML structure for adding an IAM policy binding when creating a secret. The role and serviceaccount selectors must be configured together.

```yaml
bindings:
- members:
  - serviceAccount:test-secret@project-id.iam.gserviceaccount.com
  role: roles/secretmanager.viewer
```

--------------------------------

### k8s broker configuration with per-broker cluster scope override

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_k8s.md

Example configuration that adds a per-broker override in the brokers list. The listed broker gets pod_reference_scope "cluster" to resolve pods on other nodes, while all other brokers keep the node-scoped default. access_policy is set to "enforced".

```hcl
WorkloadAttestor "k8s" {
  plugin_data {
    experimental {
      broker {
        access_policy = "enforced"
        brokers = [
          {
            id = "spiffe://example.org/broker"
            pod_reference_scope = "cluster"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### spire-server logger get

Source: https://github.com/spiffe/spire/blob/main/doc/spire_server.md

Gets the current logging level of the SPIRE Server.

```APIDOC
## spire-server logger get

### Description
Gets the current logging level of the SPIRE Server.

### Command
`spire-server logger get`

### Parameters
#### Flags
- `-socketPath` (string) - Optional - Path to the SPIRE Server API socket. Default: /tmp/spire-server/private/api.sock

```

--------------------------------

### Example 1a: Entry creation namespacing restrictions - rego policy check

Source: https://github.com/spiffe/spire/blob/main/doc/authorization_policy_engine.md

Rego rule that checks if the caller has the registrar role and the SPIFFE ID to be registered matches the allowed namespace. Used for the BatchCreateEntry method.

```rego
check_entry_create_namespace {
    input.full_method == "/spire.api.server.entry.v1.Entry/BatchCreateEntry"

    # caller has the registrar role
    b = data.entry_create_namespaces[_]
    b.user == input.caller

    # spiffe id to be registered is in correct namespace
    re_match(b.path_namespace, input.req.entries[_].spiffe_id.path)
}
```

--------------------------------

### Sample PostgreSQL datastore configuration

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_datastore_sql.md

Sample HCL configuration for the SQL datastore plugin using database_type postgres and a connection string with sslmode=disable.

```hcl
    DataStore "sql" {
        plugin_data {
            database_type = "postgres"
            connection_string = "dbname=spire_development user=spire host=127.0.0.1 sslmode=disable"
        }
    }
```

--------------------------------

### spire-agent logger get

Source: https://github.com/spiffe/spire/blob/main/doc/spire_agent.md

Gets the current logging level of the SPIRE Agent.

```APIDOC
## spire-agent logger get

### Description
Gets the current logging level of the SPIRE Agent.

### Command
`spire-agent logger get`

### Flags
- `-socketPath` (string) - Optional - Path to the SPIRE Agent Admin API socket. Default: `/tmp/spire-agent/private/admin.sock`.

```

--------------------------------

### Sample MySQL datastore configuration

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_datastore_sql.md

Sample HCL configuration for the SQL datastore plugin with MySQL, using a connection string for a local development database.

```hcl
    DataStore "sql" {
        plugin_data {
            database_type = "mysql"
            connection_string = "spire:@tcp(127.0.0.1)/spire_development?parseTime=true"
        }
    }
```

--------------------------------

### Example 1b: Sub-department namespacing with exclusions - rego policy check

Source: https://github.com/spiffe/spire/blob/main/doc/authorization_policy_engine.md

Rego rules that check for exclusions and also allow non-BatchCreateEntry methods. The first rule checks the namespace and ensures no entries match the exclusion list; the second rule allows other methods.

```rego
check_entry_create_namespace {
    input.full_method == "/spire.api.server.entry.v1.Entry/BatchCreateEntry"

    # caller has the registrar role
    b = data.entry_create_namespaces[_]
    b.user == input.caller

    # spiffe id to be registered is in correct namespace
    re_match(b.path_namespace, input.req.entries[_].spiffe_id.path)

    # check if the spiffe id to be registered doesn't hit an exclusion
    exclusions := b.path_exclusions
    exclusion_matches := { entry | entry := input.req.entries[_]; re_match(exclusions[_], entry.spiffe_id.path)}
    count(exclusion_matches) == 0
}

check_entry_create_namespace {
    input.full_method != "/spire.api.server.entry.v1.Entry/BatchCreateEntry"
}
```

--------------------------------

### spire-server localauthority x509 prepare

Source: https://github.com/spiffe/spire/blob/main/doc/spire_server.md

Prepares a new X.509 authority for use by generating a new key and injecting the resulting CA certificate into the bundle.

```APIDOC
## spire-server localauthority x509 prepare

### Description
Prepares a new X.509 authority for use by generating a new key and injecting the resulting CA certificate into the bundle.

### Command
`spire-server localauthority x509 prepare`

### Parameters
#### Flags
- `-output` (string) - Optional - Desired output format (`pretty`, `json`). Default: `pretty`
- `-socketPath` (string) - Optional - Path to the SPIRE Server API socket. Default: /tmp/spire-server/private/api.sock

```

--------------------------------

### Run SPIRE Server container as non-root user with docker run

Source: https://github.com/spiffe/spire/blob/main/doc/docker_images.md

Use this command to run the SPIRE Server container as uid 1000 and gid 1000, using the default paths from the example configuration file. Ensure the mounted configuration file has correct permissions for uid 1000.

```bash
$ docker run \
    --user 1000:1000 \
    -p 8081:8081 \
    -v /path/to/server/config:/etc/spire/server \
    ghcr.io/spiffe/spire-server:1.6.1 \
    -config /etc/spire/server/server.conf
```

--------------------------------

### Sample configuration with custom resource ID

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_nodeattestor_azure_msi.md

Sample HCL configuration for the azure_msi agent plugin with a custom resource ID.

```hcl
    NodeAttestor "azure_msi" {
        plugin_data {
            resource_id = "http://example.org/app/"
        }
    }
```

--------------------------------

### Sample HCL configuration for http_challenge

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_nodeattestor_http_challenge.md

A sample configuration for the http_challenge plugin, showing allowed_dns_patterns, required_port, and commented optional settings.

```hcl
    NodeAttestor "http_challenge" {
        plugin_data {
            # Only match hosts that start with p, have a number, then end in example.com. Ex: 'p1.example.com'
            allowed_dns_patterns = ["p[0-9]\.example\.com"]

            # Only allow clients to use port 80
            required_port = 80

            # Optional: when true, require the connecting peer IP to match a DNS address for the attested hostname
            # verify_client_ip = true

            # Change the agent's SPIFFE ID format
            # agent_path_template = "/spire/agent/http_challenge/{{ .Hostname }}"
        }
    }
```

--------------------------------

### Advanced Configuration with Multiple Tenants

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_nodeattestor_azure_imds.md

Demonstrates multiple tenants with different authentication methods (secret and token) and VM tag restrictions. Shows how to configure allowed_vm_tags per tenant.

```hcl
NodeAttestor "azure_imds" {
    plugin_data {
        tenants = {
            "production.onmicrosoft.com" = {
                secret_auth = {
                    app_id = "12345678-1234-1234-1234-123456789012"
                    app_secret = "production-secret"
                }
                restrict_to_subscriptions = [
                    "d5b40d61-272e-48da-beb9-05f295c42bd6",
                    "a1b2c3d4-5678-9012-3456-789012345678"
                ]
                allowed_vm_tags = [
                    "environment",
                    "team"
                ]
            }
            "staging.onmicrosoft.com" = {
                token_auth = {
                    app_id = "87654321-4321-4321-4321-210987654321"
                    token_path = "/var/lib/spire/staging-token"
                }
                restrict_to_subscriptions = ["e2f3g4h5-6789-0123-4567-890123456789"]
                allowed_vm_tags = [
                    "environment"
                ]
            }
        }
    }
}
```

--------------------------------

### Sample SQLite3 datastore configuration

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_datastore_sql.md

Sample HCL configuration for the SQL datastore plugin using database_type sqlite3 and a file-based connection string.

```hcl
    DataStore "sql" {
        plugin_data {
            database_type = "sqlite3"
            connection_string = "./.data/datastore.sqlite3"
        }
    }
```

--------------------------------

### View the SPIRE Server configuration file

Source: https://github.com/spiffe/spire/blob/main/doc/SPIRE101.md

Displays the default SPIRE Server configuration file.

```shell
$(in dev shell) # cat conf/server/server.conf
```

--------------------------------

### Clone the SPIRE repository

Source: https://github.com/spiffe/spire/blob/main/doc/SPIRE101.md

Clones the SPIRE GitHub repository to get the source code.

```shell
$ git clone https://github.com/spiffe/spire
```

--------------------------------

### GET /keys

Source: https://github.com/spiffe/spire/blob/main/support/oidc-discovery-provider/README.md

Returns the JSON Web Key Set (JWKS) used for JWT validation.

```APIDOC
## GET /keys

### Description
Returns the JWKS for JWT validation.

### Method
GET

### Endpoint
/keys

### Response
#### Success Response (200)
Returns the JWKS.

```

--------------------------------

### GET /.well-known/openid-configuration

Source: https://github.com/spiffe/spire/blob/main/support/oidc-discovery-provider/README.md

Returns the OIDC discovery document, which includes the JWKS URI and other OIDC metadata.

```APIDOC
## GET /.well-known/openid-configuration

### Description
Returns the OIDC discovery document.

### Method
GET

### Endpoint
/.well-known/openid-configuration

### Response
#### Success Response (200)
Returns the OIDC discovery document.

```

--------------------------------

### Sample HCL configuration for tpm_devid agent plugin

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_nodeattestor_tpm_devid.md

A sample configuration for the tpm_devid agent plugin, showing the required devid_cert_path, devid_priv_path, and devid_pub_path settings.

```hcl
    NodeAttestor "tpm_devid" {
        plugin_data {
            devid_cert_path = "/opt/spire/conf/agent/devid.crt.pem"
            devid_priv_path = "/opt/spire/conf/agent/devid.priv.blob"
            devid_pub_path = "/opt/spire/conf/agent/devid.pub.blob"
        }
    }
```

--------------------------------

### EJBCA UpstreamAuthority HCL Configuration Example

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_upstreamauthority_ejbca.md

Example HCL configuration block for the EJBCA UpstreamAuthority plugin. All required parameters are specified, and optional parameters like end_entity_name and account_binding_id are included. Note that environment variables override these values if set, and an empty block must exist to select the auth method if all parameters are provided via environment variables.

```hcl
UpstreamAuthority "ejbca" {
    plugin_data {
        hostname = "ejbca.example.com"
        ca_cert_path = "/path/to/ca_cert.pem"
        client_cert_path = "/path/to/client_cert.pem"
        client_cert_key_path = "/path/to/client_key.pem"
        ca_name = "Fake-Sub-CA"
        end_entity_profile_name = "fakeSpireIntermediateCAEEP"
        certificate_profile_name = "fakeSubCACP"
        end_entity_name = "cn"
        account_binding_id = "foo123"
    }
}
```

--------------------------------

### Sample SPIRE server configuration file (HCL)

Source: https://github.com/spiffe/spire/blob/main/doc/spire_server.md

A sample configuration file for the SPIRE server, showing the `server`, `telemetry`, and `plugins` blocks. It includes settings for trust domain, bind address, data directory, TTLs, CA subject, Prometheus telemetry with optional TLS, and plugins for DataStore, NodeAttestor, and KeyManager.

```hcl
server {
    trust_domain = "example.org"

    bind_address = "0.0.0.0"
    bind_port = "8081"
    log_level = "INFO"
    data_dir = "/opt/spire/.data/"
    default_x509_svid_ttl = "6h"
    default_jwt_svid_ttl = "5m"
    ca_ttl = "72h"
    ca_subject {
        country = ["US"]
        organization = ["SPIRE"]
        common_name = ""
    }
}

telemetry {
    Prometheus {
        port = 1234
        # optional TLS for prometheus
        tls {
            use_spire_svid = true
            authorized_spiffe_ids = [
                "spiffe://example.org/monitoring/prometheus",
            ]

            # Alternatively, configure a web certificate directly:
            # cert_file = "/path/to/cert.pem"
            # key_file = "/path/to/key.pem"
            # client_ca_file = "/path/to/ca.pem"
        }
    }
}

plugins {
    DataStore "sql" {
        plugin_data {
            database_type = "sqlite3"
            connection_string = "/opt/spire/.data/datastore.sqlite3"
        }
    }
    NodeAttestor "join_token" {
        plugin_data {}
    }
    KeyManager "disk" {
        plugin_data {
            keys_path = "/opt/spire/.data/keys.json"
        }
    }
}
```

--------------------------------

### GET /ready

Source: https://github.com/spiffe/spire/blob/main/support/oidc-discovery-provider/README.md

Health check endpoint that returns HTTP 200 as soon as requests can be served. Disabled by default.

```APIDOC
## GET /ready

### Description
Returns HTTP 200 as soon as requests can be served. Disabled by default.

### Method
GET

### Endpoint
/ready

### Response
#### Success Response (200)
Returns HTTP 200.

```

--------------------------------

### Invalid container_id_cgroup_matchers configuration

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_docker.md

Invalid example of container_id_cgroup_matchers because the patterns are ambiguous; multiple patterns can match the same input, which will cause an error.

```hcl
    container_id_cgroup_matchers = [
        "/a/b/<id>",
        "/*/b/<id>"
    ]
```

--------------------------------

### GET /live

Source: https://github.com/spiffe/spire/blob/main/support/oidc-discovery-provider/README.md

Health check endpoint that returns HTTP 200 when a keyset is available, otherwise HTTP 500. Disabled by default.

```APIDOC
## GET /live

### Description
Returns HTTP 200 as soon as a keyset is available, otherwise HTTP 500. Disabled by default.

### Method
GET

### Endpoint
/live

### Response
#### Success Response (200)
Returns HTTP 200 when a keyset is available.

#### Error Response (500)
Returns HTTP 500 when no keyset is available.

```

--------------------------------

### Sample configuration for WorkloadAttestor "unix"

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_unix.md

A minimal HCL configuration for the unix WorkloadAttestor plugin. No options are set, so defaults apply: discover_workload_path is false and workload_size_limit is 0.

```hcl
    WorkloadAttestor "unix" {
    }
```

--------------------------------

### Create entry with multiple docker:label selectors

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_docker.md

Creates a registration entry composing multiple docker:label selectors.

```shell
$ spire-server entry create \
    -parentID spiffe://example.org/host \
    -spiffeID spiffe://example.org/host/foo \
    -selector docker:label:com.example.name:foo
    -selector docker:label:com.example.cluster:prod
```

--------------------------------

### Allow clause using check_entry_delete_users

Source: https://github.com/spiffe/spire/blob/main/doc/authorization_policy_engine.md

An example allow clause that uses the check_entry_delete_users rule. Note that it is important to check how this fits with other parts of the Rego policy.

```rego
# Any allow check
allow = true {
    check_entry_delete_users
}
```

--------------------------------

### Create SPIRE Server Windows service (sc.exe create)

Source: https://github.com/spiffe/spire/blob/main/doc/spire_server.md

Creates the Windows service for SPIRE Server. The service must be created manually; SPIRE does not create it automatically.

```bash
> sc.exe create spire-server binpath=c:\spire\bin\spire-server.exe
```

--------------------------------

### Sample configuration using service account file

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_bundlepublisher_gcp_cloudstorage.md

HCL configuration for the gcp_cloudstorage plugin that uploads the trust bundle to the 'example.org' object in the 'spire-bundle' bucket. Since service_account_file is configured, authentication to the Cloud Storage API is done with the given service account file.

```hcl
    BundlePublisher "gcp_cloudstorage" {
        plugin_data {
            service_account_file = "/path/to/service/account/file"
            bucket_name = "spire-bundle"
            object_name = "example.org"
            format = "spiffe"
        }
    }
```

--------------------------------

### Basic aws_iid NodeAttestor configuration

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_nodeattestor_aws_iid.md

Sample HCL configuration for the aws_iid NodeAttestor plugin with access_key_id and secret_access_key. This is the minimal setup for AWS instance attestation.

```hcl
    NodeAttestor "aws_iid" {
        plugin_data {
            access_key_id = "ACCESS_KEY_ID"
            secret_access_key = "SECRET_ACCESS_KEY"
        }
    }
```

--------------------------------

### Build the development Docker image

Source: https://github.com/spiffe/spire/blob/main/CONTRIBUTING.md

Run this command to build the SPIRE development Docker image. This is the first step for developing inside a container.

```shell
$ make dev-image
```

--------------------------------

### Configure kubelet read-only port

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_k8s.md

Use this configuration to connect to the kubelet via its read-only port (10255). This is the simplest setup but does not use secure communication.

```hcl
WorkloadAttestor "k8s" {
  plugin_data {
    kubelet_read_only_port = 10255
  }
}
```

--------------------------------

### Create entry with docker:image_id selector

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_docker.md

Creates a registration entry using the docker:image_id selector. Use the REPOSITORY:TAG as the selector value, not the IMAGE ID column.

```shell
$ spire-server entry create \
    -parentID spiffe://example.org/host \
    -spiffeID spiffe://example.org/host/foo \
    -selector docker:image_id:envoyproxy/envoy:contrib-v1.29.1
```

--------------------------------

### Example 1b: Sub-department namespacing with exclusions - policy data

Source: https://github.com/spiffe/spire/blob/main/doc/authorization_policy_engine.md

Extends the previous policy data with an exclusion list for the finance scheduler to prevent creating entries under /finance/EMEA.

```rego
{
    "entry_create_namespaces": [
        {
            "user": "spiffe://example.org/schedulers/finance",
            "path_namespace": "^/finance",
            "path_exclusions": [
                "^/finance/EMEA"
            ]
        },
        {
            "user": "spiffe://example.org/schedulers/finance/EMEA",
            "path_namespace": "^/finance/EMEA"
        }
    ]
}
```

--------------------------------

### View help for the entry subcommand

Source: https://github.com/spiffe/spire/blob/main/doc/SPIRE101.md

Displays the help for the 'entry' subcommand of the SPIRE Server executable.

```shell
(in dev shell) # ./bin/spire-server entry --help
```

--------------------------------

### Sample configuration with default resource ID

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_nodeattestor_azure_msi.md

Sample HCL configuration for the azure_msi agent plugin using the default resource ID (Azure Resource Manager).

```hcl
    NodeAttestor "azure_msi" {
        plugin_data {
        }
    }
```

--------------------------------

### View the SPIRE Agent configuration file

Source: https://github.com/spiffe/spire/blob/main/doc/SPIRE101.md

Displays the default SPIRE Agent configuration file.

```shell
(in dev shell) # cat conf/agent/agent.conf
```

--------------------------------

### Valid container_id_cgroup_matchers configuration

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_docker.md

Valid example of container_id_cgroup_matchers using wildcard '*' and capture token '<id>'. Patterns must not be ambiguous; multiple patterns matching the same input will cause an error.

```hcl
    container_id_cgroup_matchers = [
        "/docker/<id>",
        "/my.slice/*/<id>/*"
    ]
```

--------------------------------

### Set socket templates and use -instance flag

Source: https://github.com/spiffe/spire/blob/main/doc/multiple_instances.md

Set the SPIRE_AGENT_PUBLIC_SOCKET_TEMPLATE and SPIRE_SERVER_PRIVATE_SOCKET_TEMPLATE environment variables, then run spire-agent and spire-server commands with the -instance flag. The %i placeholder is replaced with the instance name. When the env var is set and -instance is omitted, the CLI ignores the variables.

```bash
export SPIRE_AGENT_PUBLIC_SOCKET_TEMPLATE=/var/run/spire/agent/sockets/%i/public/spiffe.sock
spire-agent -instance a api watch           # uses instance "a"

export SPIRE_SERVER_PRIVATE_SOCKET_TEMPLATE=/var/run/spire/server/sockets/%i/private/api.sock
spire-server agent list -instance b         # uses instance "b"
```

--------------------------------

### Required Kubernetes RBAC Permissions for kube config User

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_nodeattestor_k8s_psat.md

Lists the minimum ClusterRole permissions the Kubernetes user in the kube config file must have: get on pods and nodes, and create on tokenreviews.

```yaml
- apiGroups: [""]
  resources: ["pods", "nodes"]
  verbs: ["get"]
- apiGroups: ["authentication.k8s.io"]
  resources: ["tokenreviews"]
  verbs: ["create"]
```

--------------------------------

### Sample http_challenge agent configuration

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_nodeattestor_http_challenge.md

A basic HCL configuration for the http_challenge agent plugin, setting the port to 80.

```hcl
    NodeAttestor "http_challenge" {
        plugin_data {
            port = 80
        }
    }
```

--------------------------------

### Guard template for missing URI SAN

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_nodeattestor_x509pop.md

Uses a conditional in the template to handle certificates without the datacenter URI SAN, preventing attestation failure. If the key is missing, the node gets no group.

```hcl
    group_template = "{{ if hasKey .URISanSelectors \"datacenter\" }}{{ .URISanSelectors.datacenter }}{{ end }}"
```

--------------------------------

### Write SVID to Disk and Inspect with OpenSSL

Source: https://github.com/spiffe/spire/blob/main/doc/SPIRE101.md

Writes the SVID and key to disk using the -write flag, then inspects the SVID certificate with openssl. The output is the SVID certificate in PEM format.

```shell
(in dev shell) # su -c "./bin/spire-agent api fetch x509 -write /tmp" workload
(in dev shell) # openssl x509 -in /tmp/svid.0.pem -text -noout
```

--------------------------------

### Create SPIRE Agent Windows service with sc.exe create

Source: https://github.com/spiffe/spire/blob/main/doc/spire_agent.md

Creates the SPIRE Agent Windows service. The service must be created by the user; SPIRE does not create it automatically. The binary path is specified with binpath.

```bash
> sc.exe create spire-agent binpath=c:\spire\bin\spire-agent.exe
```

--------------------------------

### ClusterRole for Rotating Webhook and API Service CA Bundles

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_notifier_k8sbundle.md

A ClusterRole that extends the basic permissions with get, list, patch, and watch on mutatingwebhookconfigurations, validatingwebhookconfigurations, and apiservices. Required when the plugin is configured with webhook_label or api_service_label.

```yaml
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: spire-server-cluster-role
rules:
- apiGroups: [""]
  resources: ["configmaps"]
  verbs: ["get", "patch"]
- apiGroups: ["admissionregistration.k8s.io"]
  resources: ["mutatingwebhookconfigurations", "validatingwebhookconfigurations"]
  verbs: ["get", "list", "patch", "watch"]
- apiGroups: ["apiregistration.k8s.io"]
  resources: ["apiservices"]
  verbs: ["get", "list", "patch", "watch"]

```

--------------------------------

### AWS S3 Bundle Publisher configuration for Minio server

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_bundlepublisher_aws_s3.md

Uploads the local trust bundle to the 'spire-trust-bundle' bucket as 'example.org' on a Minio server. Requires explicit endpoint, region, access_key_id, and secret_access_key.

```hcl
    BundlePublisher "aws_s3" {
        plugin_data {
            endpoint = "https://my-org-minio.example.org"
            region = "minio-sample-region"
            access_key_id  = "minio-key-id"
            secret_access_key = "minio-access-key"
            bucket = "spire-trust-bundle"
            object_key = "example.org"
            format = "spiffe"
        }
    }
```

--------------------------------

### Health check configuration (HCL)

Source: https://github.com/spiffe/spire/blob/main/doc/spire_agent.md

Enables the health check endpoint by setting listener_enabled to true. The example configures the bind address, port, and custom liveness/readiness paths. By default, the endpoint listens on localhost:80.

```hcl
health_checks {
        listener_enabled = true
        bind_address = "localhost"
        bind_port = "8080"
        live_path = "/live"
        ready_path = "/ready"
}
```

--------------------------------

### Enable compiler security hardening flags in build system

Source: https://github.com/spiffe/spire/blob/main/doc/cure53-report.pdf

Add these environment variables to the build system to enable PIE, FORTIFY_SOURCE, RELRO, and stack protector for the SPIRE binaries. The flags address the missing hardening options identified in the audit.

```bash
export GOFLAGS='-buildmode=pie'
export CGO_CPPFLAGS="-D_FORTIFY_SOURCE=2"
export CGO_LDFLAGS="-Wl,-z,relro,-z,now"
export CGO_LDFLAGS='-fstack-protector'

```

--------------------------------

### Sample HCL configuration for KeyManager disk

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_keymanager_disk.md

Configures the disk key manager with a keys_path pointing to the keys file on disk. The plugin persists private keys to the specified file.

```hcl
    KeyManager "disk" {
        plugin_data = {
            keys_path = "/opt/spire/data/server/keys.json"
        }
    }
```

--------------------------------

### Example policy data JSON object

Source: https://github.com/spiffe/spire/blob/main/doc/authorization_policy_engine.md

A JSON data object that can be used as a databinding. It contains a list of APIs with their full method names. This data is accessed via the 'data' field in rego policies.

```rego
{
    "apis": [
        { "full_method": "/spire.api.server.svid.v1.SVID/MintJWTSVID" },
        { "full_method": "/spire.api.server.bundle.v1.Bundle/GetFederatedBundle"},
        { "full_method": "/spire.api.server.svid.v1.SVID/BatchNewX509SVID"}
    ]
}
```

--------------------------------

### Sample HCL configuration for docker WorkloadAttestor

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_agent_workloadattestor_docker.md

A minimal plugin configuration with empty plugin_data. All configuration options are optional and have defaults.

```hcl
    WorkloadAttestor "docker" {
        plugin_data {
        }
    }
```

--------------------------------

### Configure gcp_cloudstorage BundlePublisher equivalent

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_notifier_gcs_bundle.md

Equivalent to the first sample configuration, but uses the gcp_cloudstorage BundlePublisher with renamed options (bucket_name, object_name) and sets format to 'pem' to keep object contents unchanged. This is part of the migration guidance.

```hcl
    BundlePublisher "gcp_cloudstorage" {
        plugin_data {
            bucket_name = "my-bucket"
            object_name = "spire-bundle.pem"
            format = "pem"
        }
    }
```

--------------------------------

### aws_s3 BundlePublisher configuration with IRSA

Source: https://github.com/spiffe/spire/blob/main/doc/plugin_server_bundlepublisher_aws_s3.md

Example HCL configuration for the aws_s3 BundlePublisher when using IRSA. The access_key_id and secret_access_key options are omitted because IRSA provides credentials via the default AWS SDK credential chain.

```hcl
    BundlePublisher "aws_s3" {
        plugin_data {
            region = "us-east-1"
            bucket = "spire-trust-bundle"
            object_key = "example.org"
            format = "spiffe"
        }
    }
```
Tokens:
Raw