openapi: 3.0.3
info:
  title: Spring Security OAuth2 API
  description: >-
    Spring Security OAuth2 provides a comprehensive OAuth 2.0 and OpenID Connect
    implementation for Spring applications. This documents the standard OAuth 2.0
    endpoints exposed by Spring Security's resource server and client components,
    including token endpoints, userinfo, JWKS, and OpenID Connect discovery.
  version: 6.3.0
  contact:
    name: Spring Security Team
    url: https://spring.io/projects/spring-security
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:8080
    description: Default application server
paths:
  /oauth2/authorize:
    get:
      operationId: authorize
      summary: OAuth2 Authorization Endpoint
      description: >-
        Initiates the OAuth 2.0 authorization code or implicit grant flow.
        Redirects the user to the authorization server for consent.
      tags:
        - Authorization
      parameters:
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum: [code]
          description: OAuth 2.0 response type
        - name: client_id
          in: query
          required: true
          schema:
            type: string
          description: Registered client ID
        - name: redirect_uri
          in: query
          required: false
          schema:
            type: string
            format: uri
          description: URI to redirect after authorization
        - name: scope
          in: query
          required: false
          schema:
            type: string
          description: Space-separated list of requested scopes (e.g., openid profile email)
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: CSRF protection state parameter
        - name: code_challenge
          in: query
          required: false
          schema:
            type: string
          description: PKCE code challenge (S256 method recommended)
        - name: code_challenge_method
          in: query
          required: false
          schema:
            type: string
            enum: [S256, plain]
          description: PKCE code challenge method
      responses:
        '302':
          description: Redirect to login or consent page
  /oauth2/token:
    post:
      operationId: issueToken
      summary: OAuth2 Token Endpoint
      description: >-
        Issues access tokens, refresh tokens, and ID tokens. Supports
        authorization_code, refresh_token, client_credentials, and
        urn:ietf:params:oauth:grant-type:jwt-bearer grant types.
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
              properties:
                grant_type:
                  type: string
                  enum:
                    - authorization_code
                    - refresh_token
                    - client_credentials
                    - urn:ietf:params:oauth:grant-type:jwt-bearer
                code:
                  type: string
                  description: Authorization code (for authorization_code grant)
                redirect_uri:
                  type: string
                  description: Redirect URI matching the authorization request
                code_verifier:
                  type: string
                  description: PKCE code verifier
                refresh_token:
                  type: string
                  description: Refresh token (for refresh_token grant)
                scope:
                  type: string
                  description: Requested scope
                client_id:
                  type: string
                client_secret:
                  type: string
      security:
        - basicAuth: []
        - {}
      responses:
        '200':
          description: Token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Token request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '401':
          description: Client authentication failed
  /oauth2/introspect:
    post:
      operationId: introspectToken
      summary: OAuth2 Token Introspection
      description: Validates a token and returns its metadata per RFC 7662
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
                  description: Token to introspect
                token_type_hint:
                  type: string
                  enum: [access_token, refresh_token]
      security:
        - basicAuth: []
      responses:
        '200':
          description: Introspection response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectionResponse'
  /oauth2/revoke:
    post:
      operationId: revokeToken
      summary: OAuth2 Token Revocation
      description: Revokes an access or refresh token per RFC 7009
      tags:
        - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - token
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
                  enum: [access_token, refresh_token]
      security:
        - basicAuth: []
      responses:
        '200':
          description: Token revoked successfully
  /userinfo:
    get:
      operationId: getUserInfo
      summary: OpenID Connect UserInfo Endpoint
      description: Returns claims about the authenticated end-user per OpenID Connect Core
      tags:
        - OpenID Connect
      security:
        - bearerAuth: []
      responses:
        '200':
          description: UserInfo claims
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Unauthorized - invalid or missing token
    post:
      operationId: getUserInfoPost
      summary: OpenID Connect UserInfo Endpoint (POST)
      description: Returns claims about the authenticated end-user via POST method
      tags:
        - OpenID Connect
      security:
        - bearerAuth: []
      responses:
        '200':
          description: UserInfo claims
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
  /oauth2/jwks:
    get:
      operationId: getJwks
      summary: JSON Web Key Set Endpoint
      description: Returns the public keys used to verify JWT signatures
      tags:
        - Keys
      responses:
        '200':
          description: JWKS document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwksResponse'
  /.well-known/openid-configuration:
    get:
      operationId: getOpenIdConfiguration
      summary: OpenID Connect Discovery
      description: Returns the OpenID Connect Provider configuration metadata
      tags:
        - Discovery
      responses:
        '200':
          description: OpenID Connect configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenIdConfiguration'
  /.well-known/oauth-authorization-server:
    get:
      operationId: getAuthorizationServerMetadata
      summary: OAuth2 Authorization Server Metadata
      description: Returns OAuth 2.0 authorization server metadata per RFC 8414
      tags:
        - Discovery
      responses:
        '200':
          description: Authorization server metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationServerMetadata'
  /logout:
    post:
      operationId: logout
      summary: Spring Security Logout
      description: Invalidates the current session and clears security context
      tags:
        - Session
      parameters:
        - name: _csrf
          in: query
          required: false
          schema:
            type: string
          description: CSRF token
      responses:
        '302':
          description: Redirect to logout success URL
  /login:
    get:
      operationId: getLoginPage
      summary: Get Login Page
      description: Returns the default Spring Security login form
      tags:
        - Session
      responses:
        '200':
          description: Login page HTML
          content:
            text/html:
              schema:
                type: string
    post:
      operationId: processLogin
      summary: Process Login
      description: Processes username/password login form submission
      tags:
        - Session
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                password:
                  type: string
                  format: password
                _csrf:
                  type: string
                remember-me:
                  type: string
      responses:
        '302':
          description: Redirect on success or failure
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          description: Token lifetime in seconds
        refresh_token:
          type: string
        scope:
          type: string
        id_token:
          type: string
          description: JWT ID token (OpenID Connect only)
    OAuthError:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid_request
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unsupported_grant_type
            - invalid_scope
        error_description:
          type: string
    IntrospectionResponse:
      type: object
      required:
        - active
      properties:
        active:
          type: boolean
        scope:
          type: string
        client_id:
          type: string
        username:
          type: string
        token_type:
          type: string
        exp:
          type: integer
        iat:
          type: integer
        sub:
          type: string
        aud:
          type: string
        iss:
          type: string
        jti:
          type: string
    UserInfo:
      type: object
      properties:
        sub:
          type: string
          description: Subject identifier
        name:
          type: string
        given_name:
          type: string
        family_name:
          type: string
        email:
          type: string
          format: email
        email_verified:
          type: boolean
        picture:
          type: string
          format: uri
        locale:
          type: string
        updated_at:
          type: integer
    JwksResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            type: object
            properties:
              kty:
                type: string
              kid:
                type: string
              use:
                type: string
              alg:
                type: string
              n:
                type: string
              e:
                type: string
    OpenIdConfiguration:
      type: object
      properties:
        issuer:
          type: string
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        userinfo_endpoint:
          type: string
        jwks_uri:
          type: string
        scopes_supported:
          type: array
          items:
            type: string
        response_types_supported:
          type: array
          items:
            type: string
        grant_types_supported:
          type: array
          items:
            type: string
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
        claims_supported:
          type: array
          items:
            type: string
        code_challenge_methods_supported:
          type: array
          items:
            type: string
    AuthorizationServerMetadata:
      type: object
      properties:
        issuer:
          type: string
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        jwks_uri:
          type: string
        introspection_endpoint:
          type: string
        revocation_endpoint:
          type: string
        grant_types_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
tags:
  - name: Authorization
  - name: Discovery
  - name: Keys
  - name: OpenID Connect
  - name: Session
  - name: Token