SPIRE Discovery API

openapi: 3.2.0
info:
  title: SPIRE OIDC Provider Discovery API
  description: The SPIRE OIDC Discovery Provider is a helper component that exposes a minimal OpenID Connect discovery document and JSON Web Key Set (JWKS) endpoint. This allows workloads to present JWT-SVIDs issued by SPIRE to systems that support standard OIDC token validation, including cloud provider IAM systems such as AWS, GCP, and Azure. The provider derives its key material from the SPIRE Server or Agent trust bundle and serves it over HTTPS.
  version: '1.0'
  contact:
    name: SPIFFE Community
    url: https://spiffe.io/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{domain}
  description: SPIRE OIDC Discovery Provider
  variables:
    domain:
      default: oidc-discovery.example.com
      description: The domain name configured for the OIDC discovery provider instance.
tags:
- name: Discovery
  description: OpenID Connect discovery document endpoint that describes the OIDC provider configuration and supported capabilities.
paths:
  /.well-known/openid-configuration:
    get:
      operationId: getOpenIDConfiguration
      summary: SPIRE Get OpenID Connect discovery document
      description: Returns the OpenID Connect discovery document describing the OIDC provider's configuration. The document includes the issuer URL, JWKS URI, supported response types, subject types, and supported signing algorithms. This endpoint is used by OIDC-compatible systems to auto-configure themselves to validate JWT-SVIDs issued by SPIRE. The path prefix can be customized via the server_path_prefix option.
      tags:
      - Discovery
      responses:
        '200':
          description: OpenID Connect discovery document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIDConfiguration'
components:
  schemas:
    OpenIDConfiguration:
      type: object
      description: OpenID Connect discovery document returned by the /.well-known/openid-configuration endpoint. Describes the OIDC provider's issuer, key location, and supported capabilities for JWT validation.
      required:
      - issuer
      - jwks_uri
      - authorization_endpoint
      - response_types_supported
      - subject_types_supported
      - id_token_signing_alg_values_supported
      properties:
        issuer:
          type: string
          format: uri
          description: The HTTPS URL identifying the OIDC provider. This must match the issuer claim in JWT-SVIDs issued by SPIRE and corresponds to the trust domain's SPIFFE ID base URL.
          example: https://oidc-discovery.example.com
        jwks_uri:
          type: string
          format: uri
          description: URL of the JSON Web Key Set document containing public keys for verifying JWT signatures. Typically the /keys endpoint on the same host.
          example: https://oidc-discovery.example.com/keys
        authorization_endpoint:
          type: string
          format: uri
          description: URL of the authorization endpoint. SPIRE's OIDC provider does not perform interactive authorization flows; this field is present for OIDC spec compliance but is not functional.
          example: https://oidc-discovery.example.com/authorize
        response_types_supported:
          type: array
          description: List of OAuth 2.0 response type values that this authorization server supports. SPIRE supports the id_token response type.
          items:
            type: string
            enum:
            - id_token
        subject_types_supported:
          type: array
          description: List of subject identifier types supported. SPIRE uses the public subject type.
          items:
            type: string
            enum:
            - public
        id_token_signing_alg_values_supported:
          type: array
          description: List of JWS signing algorithms supported for JWT-SVID signing. SPIRE supports RS256, ES256, and ES384.
          items:
            type: string
            enum:
            - RS256
            - ES256
            - ES384
externalDocs:
  description: SPIRE OIDC Discovery Provider Documentation
  url: https://github.com/spiffe/spire/tree/main/support/oidc-discovery-provider