tegwick
1353267569
Assistant: codex Assistant-Model: gpt-5.6-luna Assistant-Session: 01a087b0-7b1e-7531-8ef3-6525ebaf7ee7
90 lines
2.4 KiB
Markdown
90 lines
2.4 KiB
Markdown
# FIAM v0.2 — OpenAPI Security Ingest Profile
|
|
|
|
## Purpose
|
|
|
|
Map declared OpenAPI security schemes and Security Requirement Objects into FIAM Security profiles without collapsing security into interface-family names.
|
|
|
|
## Supported Security Scheme families
|
|
|
|
The draft.4 adapter recognizes:
|
|
|
|
- `apiKey`;
|
|
- `http` Basic;
|
|
- `http` Bearer;
|
|
- `oauth2`;
|
|
- `openIdConnect`;
|
|
- `mutualTLS`.
|
|
|
|
These map to FIAM authentication/credential terms while preserving the original scheme metadata as facets.
|
|
|
|
## Requirement semantics
|
|
|
|
The adapter preserves OpenAPI requirement composition.
|
|
|
|
Within one Security Requirement Object:
|
|
|
|
```text
|
|
scheme A + scheme B = both required
|
|
```
|
|
|
|
Across multiple Security Requirement Objects:
|
|
|
|
```text
|
|
requirement 1 OR requirement 2
|
|
```
|
|
|
|
An empty requirement object `{}` represents an anonymous-access alternative.
|
|
|
|
Operation-level `security` overrides top-level security. An empty operation list `security: []` removes inherited security for that operation.
|
|
|
|
## FIAM profiles
|
|
|
|
Top-level requirements create Security profiles applying to the InterfaceContract.
|
|
|
|
Operation-level requirements create Security profiles applying to the Operation.
|
|
|
|
Profiles retain, where applicable:
|
|
|
|
- source scheme name/type;
|
|
- alternative number;
|
|
- required scopes;
|
|
- API-key location/name;
|
|
- OAuth flow names;
|
|
- OpenID Connect discovery URL;
|
|
- credential / transport-security semantics.
|
|
|
|
## Effective-security Lens
|
|
|
|
`tools/security_coverage_lens.py` evaluates effective declared security per operation.
|
|
|
|
Current classes:
|
|
|
|
```text
|
|
inherited-contract-security
|
|
operation-specific
|
|
anonymous-access-allowed
|
|
explicitly-unprotected
|
|
no-declared-security
|
|
```
|
|
|
|
The fixture `real-world/openapi/estate-hardening/security-api.yaml` covers the first four classes.
|
|
|
|
## Runtime boundary
|
|
|
|
Generic HTTP OTLP spans do not establish whether application authentication occurred.
|
|
|
|
Therefore the absence of an authentication-specific telemetry signal is **unknown**, not evidence of unprotected access.
|
|
|
|
A future runtime security source may enrich these same FIAM Security profiles/assertions; no Core change is implied.
|
|
|
|
## Current limitations
|
|
|
|
The reference OpenAPI adapter does not yet fully resolve:
|
|
|
|
- external `$ref` documents;
|
|
- callbacks and webhooks;
|
|
- all Server Object variable expansion;
|
|
- security schemes declared by external URI rather than local component reference;
|
|
- APIs intentionally split across multiple OpenAPI files.
|
|
|
|
These are adapter/composition concerns and remain outside the frozen Core.
|