0
# Security System
1

2
The security system provides comprehensive authentication and authorization scheme definitions for OpenAPI specifications. This includes API key authentication, HTTP authentication schemes, OAuth 2.0 flows, and OpenID Connect configurations with complete flow definitions and security requirements.
3

4
## Capabilities
5

6
### Security Scheme Definition
7

8
Defines security schemes that can be used to secure API operations.
9

10
```python { .api }
11
@dataclass
12
class Security:
13
    type: SecurityType
14
    location: Optional[BaseLocation] = None
15
    description: Optional[str] = None
16
    name: Optional[str] = None
17
    scheme: Optional[AuthenticationScheme] = None
18
    bearer_format: Optional[str] = None
19
    flows: dict[OAuthFlowType, OAuthFlow] = field(default_factory=dict)
20
    url: Optional[str] = None
21
    extensions: Optional[dict] = field(default_factory=dict)
22
```
23

24
**Properties:**
25
- `type`: Security scheme type (apiKey, http, oauth2, openIdConnect)
26
- `location`: Parameter location for API key schemes (header, query, cookie)
27
- `description`: Human-readable description of the security scheme
28
- `name`: Parameter name for API key schemes
29
- `scheme`: HTTP authentication scheme (basic, bearer, digest, etc.)
30
- `bearer_format`: Hint about bearer token format (e.g., "JWT")
31
- `flows`: OAuth 2.0 flow configurations by flow type
32
- `url`: OpenID Connect discovery URL
33
- `extensions`: Custom security scheme extensions
34

35
### OAuth Flow Configuration
36

37
Defines OAuth 2.0 authorization flow configurations with URLs and scopes.
38

39
```python { .api }
40
@dataclass
41
class OAuthFlow:
42
    refresh_url: Optional[str] = None
43
    authorization_url: Optional[str] = None
44
    token_url: Optional[str] = None
45
    scopes: dict[str, str] = field(default_factory=dict)
46
    extensions: Optional[dict] = field(default_factory=dict)
47
```
48

49
**Properties:**
50
- `refresh_url`: URL for refreshing tokens
51
- `authorization_url`: Authorization endpoint URL (for authorization code and implicit flows)
52
- `token_url`: Token endpoint URL (for authorization code, password, and client credentials flows)
53
- `scopes`: Available OAuth scopes mapped to their descriptions
54
- `extensions`: Custom OAuth flow extensions
55

56
### Usage Examples
57

58
Access security schemes:
59
```python
60
from openapi_parser import parse
61
from openapi_parser.enumeration import SecurityType, AuthenticationScheme
62

63
spec = parse('api-spec.yml')
64

65
# List all security schemes
66
for name, security in spec.security_schemas.items():
67
    print(f"Security scheme: {name}")
68
    print(f"  Type: {security.type.value}")
69
    
70
    if security.type == SecurityType.API_KEY:
71
        print(f"  Parameter: {security.name} (in {security.location.value})")
72
    
73
    elif security.type == SecurityType.HTTP:
74
        print(f"  Scheme: {security.scheme.value}")
75
        if security.bearer_format:
76
            print(f"  Bearer format: {security.bearer_format}")
77
    
78
    elif security.type == SecurityType.OAUTH2:
79
        print(f"  OAuth flows:")
80
        for flow_type, flow in security.flows.items():
81
            print(f"    {flow_type.value}:")
82
            if flow.authorization_url:
83
                print(f"      Auth URL: {flow.authorization_url}")
84
            if flow.token_url:
85
                print(f"      Token URL: {flow.token_url}")
86
            if flow.scopes:
87
                print(f"      Scopes: {', '.join(flow.scopes.keys())}")
88
    
89
    elif security.type == SecurityType.OPEN_ID_CONNECT:
90
        print(f"  OpenID Connect URL: {security.url}")
91
```
92

93
Check operation security requirements:
94
```python
95
# Examine security requirements for operations
96
for path in spec.paths:
97
    for operation in path.operations:
98
        if operation.security:
99
            print(f"{operation.method.value.upper()} {path.url}")
100
            
101
            for requirement in operation.security:
102
                for scheme_name, scopes in requirement.items():
103
                    if scopes:
104
                        print(f"  Requires {scheme_name} with scopes: {', '.join(scopes)}")
105
                    else:
106
                        print(f"  Requires {scheme_name}")
107
```
108

109
Working with OAuth flows:
110
```python
111
# Find OAuth 2.0 security schemes and their flows
112
for name, security in spec.security_schemas.items():
113
    if security.type == SecurityType.OAUTH2:
114
        print(f"OAuth 2.0 scheme: {name}")
115
        
116
        for flow_type, flow in security.flows.items():
117
            print(f"  Flow: {flow_type.value}")
118
            
119
            # Show available scopes
120
            if flow.scopes:
121
                print(f"    Available scopes:")
122
                for scope, description in flow.scopes.items():
123
                    print(f"      {scope}: {description}")
124
            
125
            # Show flow URLs
126
            if flow.authorization_url:
127
                print(f"    Authorization URL: {flow.authorization_url}")
128
            if flow.token_url:
129
                print(f"    Token URL: {flow.token_url}")
130
            if flow.refresh_url:
131
                print(f"    Refresh URL: {flow.refresh_url}")
132
```
133

134
API key security examples:
135
```python
136
# Find API key security schemes
137
for name, security in spec.security_schemas.items():
138
    if security.type == SecurityType.API_KEY:
139
        print(f"API Key scheme: {name}")
140
        print(f"  Parameter: {security.name}")
141
        print(f"  Location: {security.location.value}")
142
        
143
        if security.description:
144
            print(f"  Description: {security.description}")
145
```
146

147
HTTP authentication examples:
148
```python
149
# Find HTTP authentication schemes
150
for name, security in spec.security_schemas.items():
151
    if security.type == SecurityType.HTTP:
152
        print(f"HTTP auth scheme: {name}")
153
        print(f"  Scheme: {security.scheme.value}")
154
        
155
        if security.scheme == AuthenticationScheme.BEARER and security.bearer_format:
156
            print(f"  Bearer format: {security.bearer_format}")
157
        
158
        if security.description:
159
            print(f"  Description: {security.description}")
160
```