Spring Security OAuth2 API
OAuth 2.0 and OpenID Connect support for Spring Security. Provides client registration, authorization code flow, token endpoint, token refresh, PKCE support, and resource server JWT validation.
OpenAPI Specification
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