0
# Security Configuration
1

2
Complete security scheme definitions supporting OAuth2 flows, API keys, HTTP authentication, OpenID Connect, and mutual TLS. This system provides comprehensive security documentation for REST APIs with flexible authentication and authorization patterns.
3

4
## Capabilities
5

6
### Security Scheme Definition
7

8
Defines security schemes in the OpenAPI components section with comprehensive authentication method support.
9

10
```java { .api }
11
/**
12
 * Defines security schemes for API authentication
13
 * Applied to: TYPE, METHOD
14
 * Repeatable: Yes
15
 */
16
@SecurityScheme(
17
    name = "bearerAuth",                            // Security scheme name (required)
18
    type = SecuritySchemeType.HTTP,                 // Security scheme type (required)
19
    description = "JWT Bearer token authentication", // Scheme description
20
    
21
    // API Key configuration
22
    paramName = "X-API-Key",                        // Parameter name for API key
23
    in = SecuritySchemeIn.HEADER,                   // Location of API key
24
    
25
    // HTTP authentication
26
    scheme = "bearer",                              // HTTP auth scheme (basic, bearer, etc.)
27
    bearerFormat = "JWT",                           // Bearer token format
28
    
29
    // OAuth2 configuration  
30
    flows = @OAuthFlows(...),                       // OAuth2 flow definitions
31
    
32
    // OpenID Connect
33
    openIdConnectUrl = "https://auth.example.com/.well-known/openid_configuration",
34
    
35
    extensions = {@Extension(...)},                 // Custom extensions
36
    ref = "#/components/securitySchemes/BearerAuth" // Reference to component
37
)
38
```
39

40
**Security Scheme Types:**
41

42
```java { .api }
43
enum SecuritySchemeType {
44
    DEFAULT(""),
45
    APIKEY("apiKey"),           // API key authentication
46
    HTTP("http"),               // HTTP authentication (basic, bearer, etc.)
47
    OAUTH2("oauth2"),           // OAuth2 authentication
48
    OPENIDCONNECT("openIdConnect"), // OpenID Connect
49
    MUTUALTLS("mutualTLS")      // Mutual TLS authentication
50
}
51
```
52

53
**Security Scheme Locations:**
54

55
```java { .api }
56
enum SecuritySchemeIn {
57
    DEFAULT(""),
58
    HEADER("header"),           // Header parameter
59
    QUERY("query"),             // Query parameter  
60
    COOKIE("cookie")            // Cookie parameter
61
}
62
```
63

64
**Usage Examples:**
65

66
```java
67
// JWT Bearer token
68
@SecurityScheme(
69
    name = "bearerAuth",
70
    type = SecuritySchemeType.HTTP,
71
    scheme = "bearer", 
72
    bearerFormat = "JWT",
73
    description = "JWT Bearer token for API authentication"
74
)
75

76
// API Key in header
77
@SecurityScheme(
78
    name = "apiKeyAuth",
79
    type = SecuritySchemeType.APIKEY,
80
    in = SecuritySchemeIn.HEADER,
81
    paramName = "X-API-Key",
82
    description = "API key authentication via header"
83
)
84

85
// Basic HTTP authentication
86
@SecurityScheme(
87
    name = "basicAuth",
88
    type = SecuritySchemeType.HTTP,
89
    scheme = "basic",
90
    description = "Basic HTTP authentication"
91
)
92

93
// OAuth2 with multiple flows
94
@SecurityScheme(
95
    name = "oauth2",
96
    type = SecuritySchemeType.OAUTH2,
97
    description = "OAuth2 authentication with multiple flows",
98
    flows = @OAuthFlows(
99
        authorizationCode = @OAuthFlow(
100
            authorizationUrl = "https://auth.example.com/oauth/authorize",
101
            tokenUrl = "https://auth.example.com/oauth/token",
102
            refreshUrl = "https://auth.example.com/oauth/refresh",
103
            scopes = {
104
                @OAuthScope(name = "read", description = "Read access to user data"),
105
                @OAuthScope(name = "write", description = "Write access to user data"),
106
                @OAuthScope(name = "admin", description = "Administrative access")
107
            }
108
        ),
109
        clientCredentials = @OAuthFlow(
110
            tokenUrl = "https://auth.example.com/oauth/token",
111
            scopes = {
112
                @OAuthScope(name = "api:read", description = "Read API access"),
113
                @OAuthScope(name = "api:write", description = "Write API access")
114
            }
115
        )
116
    )
117
)
118

119
// OpenID Connect
120
@SecurityScheme(
121
    name = "oidc",
122
    type = SecuritySchemeType.OPENIDCONNECT,
123
    openIdConnectUrl = "https://auth.example.com/.well-known/openid_configuration",
124
    description = "OpenID Connect authentication"
125
)
126

127
// Mutual TLS
128
@SecurityScheme(
129
    name = "mutualTLS",
130
    type = SecuritySchemeType.MUTUALTLS,
131
    description = "Mutual TLS certificate authentication"
132
)
133
```
134

135
### Security Schemes Container
136

137
Container for multiple security scheme definitions.
138

139
```java { .api }
140
/**
141
 * Container for multiple SecurityScheme annotations
142
 */
143
@SecuritySchemes({
144
    @SecurityScheme(name = "bearerAuth", type = SecuritySchemeType.HTTP, scheme = "bearer"),
145
    @SecurityScheme(name = "apiKey", type = SecuritySchemeType.APIKEY, in = SecuritySchemeIn.HEADER, paramName = "X-API-Key"),
146
    @SecurityScheme(name = "oauth2", type = SecuritySchemeType.OAUTH2, flows = @OAuthFlows(...))
147
})
148
```
149

150
### Security Requirements
151

152
Defines which security schemes are required for operations or the entire API.
153

154
```java { .api }
155
/**
156
 * Defines security requirements for operations
157
 * Applied to: METHOD, TYPE  
158
 * Repeatable: Yes
159
 */
160
@SecurityRequirement(
161
    name = "bearerAuth",                            // Security scheme name (required)
162
    scopes = {"read:users", "write:users"}         // Required scopes (for OAuth2/OIDC)
163
)
164
```
165

166
**Usage Examples:**
167

168
```java
169
// Single security requirement
170
@GET
171
@Operation(summary = "Get user profile")
172
@SecurityRequirement(name = "bearerAuth")
173
public Response getUserProfile() {}
174

175
// Multiple security requirements (any one satisfies)
176
@GET
177
@Operation(summary = "Get public or authenticated content")
178
@SecurityRequirement(name = "bearerAuth")
179
@SecurityRequirement(name = "apiKey")
180
public Response getContent() {}
181

182
// OAuth2 with specific scopes
183
@POST
184
@Operation(summary = "Create user")
185
@SecurityRequirement(name = "oauth2", scopes = {"user:create", "admin"})
186
public Response createUser(@RequestBody CreateUserRequest request) {}
187

188
// Global security on class
189
@SecurityRequirement(name = "bearerAuth")
190
@Path("/admin")
191
public class AdminResource {
192
    // All operations inherit this security requirement
193
}
194

195
// Override security for specific operation
196
@GET
197
@Operation(summary = "Public health check")
198
@SecurityRequirement(name = "")  // Empty name = no security required
199
public Response healthCheck() {}
200
```
201

202
### Security Requirements Container
203

204
Container for multiple security requirement definitions.
205

206
```java { .api }
207
/**
208
 * Container for multiple SecurityRequirement annotations  
209
 */
210
@SecurityRequirements({
211
    @SecurityRequirement(name = "bearerAuth"),
212
    @SecurityRequirement(name = "apiKey"),
213
    @SecurityRequirement(name = "oauth2", scopes = {"read", "write"})
214
})
215
```
216

217
### OAuth2 Flow Configuration
218

219
Comprehensive OAuth2 flow definitions supporting all standard OAuth2 flows.
220

221
```java { .api }
222
/**
223
 * Defines OAuth2 flows configuration
224
 */
225
@OAuthFlows(
226
    implicit = @OAuthFlow(...),                     // Implicit flow
227
    password = @OAuthFlow(...),                     // Resource owner password flow
228
    clientCredentials = @OAuthFlow(...),            // Client credentials flow
229
    authorizationCode = @OAuthFlow(...),            // Authorization code flow
230
    extensions = {@Extension(...)}                  // Custom extensions
231
)
232

233
/**
234
 * Individual OAuth2 flow definition
235
 */
236
@OAuthFlow(
237
    authorizationUrl = "https://auth.example.com/oauth/authorize", // Authorization URL
238
    tokenUrl = "https://auth.example.com/oauth/token",            // Token URL (required)
239
    refreshUrl = "https://auth.example.com/oauth/refresh",        // Refresh URL
240
    scopes = {                                     // Available scopes
241
        @OAuthScope(name = "read", description = "Read access"),
242
        @OAuthScope(name = "write", description = "Write access")
243
    },
244
    extensions = {@Extension(...)}                  // Custom extensions
245
)
246

247
/**
248
 * OAuth2 scope definition
249
 */
250
@OAuthScope(
251
    name = "read:users",                           // Scope name (required)
252
    description = "Read access to user information" // Scope description
253
)
254
```
255

256
**OAuth2 Flow Examples:**
257

258
```java
259
// Authorization Code Flow (most common for web apps)
260
@SecurityScheme(
261
    name = "oauth2AuthCode",
262
    type = SecuritySchemeType.OAUTH2,
263
    flows = @OAuthFlows(
264
        authorizationCode = @OAuthFlow(
265
            authorizationUrl = "https://auth.example.com/oauth/authorize",
266
            tokenUrl = "https://auth.example.com/oauth/token", 
267
            refreshUrl = "https://auth.example.com/oauth/refresh",
268
            scopes = {
269
                @OAuthScope(name = "profile", description = "Access to user profile"),
270
                @OAuthScope(name = "email", description = "Access to user email"),
271
                @OAuthScope(name = "admin", description = "Administrative access")
272
            }
273
        )
274
    )
275
)
276

277
// Client Credentials Flow (for service-to-service)
278
@SecurityScheme(
279
    name = "oauth2ClientCreds", 
280
    type = SecuritySchemeType.OAUTH2,
281
    flows = @OAuthFlows(
282
        clientCredentials = @OAuthFlow(
283
            tokenUrl = "https://auth.example.com/oauth/token",
284
            scopes = {
285
                @OAuthScope(name = "api:read", description = "Read API access"),
286
                @OAuthScope(name = "api:write", description = "Write API access"),
287
                @OAuthScope(name = "api:admin", description = "Admin API access")
288
            }
289
        )
290
    )
291
)
292

293
// Implicit Flow (for SPAs, deprecated but still supported)
294
@SecurityScheme(
295
    name = "oauth2Implicit",
296
    type = SecuritySchemeType.OAUTH2,
297
    flows = @OAuthFlows(
298
        implicit = @OAuthFlow(
299
            authorizationUrl = "https://auth.example.com/oauth/authorize",
300
            scopes = {
301
                @OAuthScope(name = "read", description = "Read access"),
302
                @OAuthScope(name = "write", description = "Write access")
303
            }
304
        )
305
    )
306
)
307

308
// Password Flow (for trusted first-party clients)
309
@SecurityScheme(
310
    name = "oauth2Password",
311
    type = SecuritySchemeType.OAUTH2, 
312
    flows = @OAuthFlows(
313
        password = @OAuthFlow(
314
            tokenUrl = "https://auth.example.com/oauth/token",
315
            refreshUrl = "https://auth.example.com/oauth/refresh",
316
            scopes = {
317
                @OAuthScope(name = "full_access", description = "Full user access")
318
            }
319
        )
320
    )
321
)
322

323
// Multiple flows in one scheme
324
@SecurityScheme(
325
    name = "oauth2Multi",
326
    type = SecuritySchemeType.OAUTH2,
327
    flows = @OAuthFlows(
328
        authorizationCode = @OAuthFlow(
329
            authorizationUrl = "https://auth.example.com/oauth/authorize", 
330
            tokenUrl = "https://auth.example.com/oauth/token",
331
            scopes = {@OAuthScope(name = "user", description = "User access")}
332
        ),
333
        clientCredentials = @OAuthFlow(
334
            tokenUrl = "https://auth.example.com/oauth/token",
335
            scopes = {@OAuthScope(name = "service", description = "Service access")}
336
        )
337
    )
338
)
339
```
340

341
## Security Implementation Patterns
342

343
### Global Security Configuration
344

345
```java
346
@OpenAPIDefinition(
347
    info = @Info(title = "Secure API", version = "1.0"),
348
    security = {
349
        @SecurityRequirement(name = "bearerAuth"),
350
        @SecurityRequirement(name = "apiKey")  // Either bearer OR API key
351
    }
352
)
353
@SecuritySchemes({
354
    @SecurityScheme(
355
        name = "bearerAuth",
356
        type = SecuritySchemeType.HTTP,
357
        scheme = "bearer",
358
        bearerFormat = "JWT"
359
    ),
360
    @SecurityScheme(
361
        name = "apiKey", 
362
        type = SecuritySchemeType.APIKEY,
363
        in = SecuritySchemeIn.HEADER,
364
        paramName = "X-API-Key"
365
    )
366
})
367
public class SecureApplication {}
368
```
369

370
### Resource-Level Security
371

372
```java
373
@Path("/admin")
374
@SecurityRequirement(name = "oauth2", scopes = {"admin"})
375
public class AdminResource {
376
    
377
    @GET
378
    @Path("/users")
379
    @Operation(summary = "List all users - requires admin scope")
380
    public Response listUsers() {}
381
    
382
    @DELETE
383
    @Path("/users/{id}")
384
    @Operation(summary = "Delete user - requires admin scope") 
385
    @SecurityRequirement(name = "oauth2", scopes = {"admin", "user:delete"})
386
    public Response deleteUser(@PathParam("id") Long id) {}
387
}
388
```
389

390
### Operation-Level Security Override
391

392
```java
393
@Path("/api")
394
@SecurityRequirement(name = "bearerAuth")  // Default for all operations
395
public class ApiResource {
396
    
397
    @GET
398
    @Path("/public")
399
    @Operation(summary = "Public endpoint")
400
    @SecurityRequirement(name = "")  // Override: no security required
401
    public Response publicEndpoint() {}
402
    
403
    @GET
404
    @Path("/admin")
405
    @Operation(summary = "Admin endpoint")
406
    @SecurityRequirement(name = "oauth2", scopes = {"admin"})  // Override: OAuth2 required
407
    public Response adminEndpoint() {}
408
}
409
```
410

411
### Multiple Security Options
412

413
```java
414
@GET
415
@Operation(summary = "Flexible authentication endpoint")
416
@SecurityRequirements({
417
    @SecurityRequirement(name = "bearerAuth"),        // Option 1: JWT
418
    @SecurityRequirement(name = "apiKey"),            // Option 2: API Key  
419
    @SecurityRequirement(name = "basicAuth"),         // Option 3: Basic Auth
420
    @SecurityRequirement(name = "oauth2", scopes = {"read"}) // Option 4: OAuth2
421
})
422
public Response flexibleAuth() {}
423
```
424

425
### Combined Security Requirements
426

427
```java
428
@GET
429
@Operation(summary = "Requires both API key AND bearer token")
430
@SecurityRequirement(name = "apiKey")     // Separate requirements = both required
431
@SecurityRequirement(name = "bearerAuth") // Both must be satisfied
432
public Response combinedSecurity() {}
433

434
// Alternative syntax for combined requirements
435
@GET
436
@Operation(
437
    summary = "Multiple security schemes",
438
    security = {
439
        @SecurityRequirement(name = "apiKey"),
440
        @SecurityRequirement(name = "bearerAuth")
441
    }
442
)
443
public Response alternativeCombined() {}
444
```
445

446
## Advanced Security Patterns
447

448
### Custom Security Extensions
449

450
```java
451
@SecurityScheme(
452
    name = "customAuth",
453
    type = SecuritySchemeType.HTTP,
454
    scheme = "custom",
455
    extensions = {
456
        @Extension(
457
            name = "x-auth-type",
458
            properties = @ExtensionProperty(name = "type", value = "signature")
459
        ),
460
        @Extension(
461
            name = "x-signature-algorithm", 
462
            properties = @ExtensionProperty(name = "algorithm", value = "HMAC-SHA256")
463
        )
464
    }
465
)
466
```
467

468
### Environment-Specific Security
469

470
```java
471
@SecurityScheme(
472
    name = "envSpecificAuth",
473
    type = SecuritySchemeType.OAUTH2,
474
    flows = @OAuthFlows(
475
        authorizationCode = @OAuthFlow(
476
            authorizationUrl = "https://auth.{environment}.example.com/oauth/authorize",
477
            tokenUrl = "https://auth.{environment}.example.com/oauth/token"
478
        )
479
    ),
480
    extensions = {
481
        @Extension(
482
            name = "x-environment-urls",
483
            properties = {
484
                @ExtensionProperty(name = "dev", value = "https://auth.dev.example.com"),
485
                @ExtensionProperty(name = "staging", value = "https://auth.staging.example.com"),
486
                @ExtensionProperty(name = "prod", value = "https://auth.example.com")
487
            }
488
        )
489
    }
490
)
491
```
492

493
### Conditional Security Based on Scopes
494

495
```java
496
@GET
497
@Path("/users/{id}")
498
@Operation(summary = "Get user - different access levels")
499
@SecurityRequirements({
500
    @SecurityRequirement(name = "oauth2", scopes = {"user:read:own"}),     // Can read own data
501
    @SecurityRequirement(name = "oauth2", scopes = {"user:read:all"}),     // Can read any user data
502
    @SecurityRequirement(name = "oauth2", scopes = {"admin"})              // Admin access
503
})
504
public Response getUser(@PathParam("id") Long id) {}
505
```