facetted-interfaces/history/FIAM_v0.2_Draft6/OPENAPI-SECURITY-INGEST-v0.2.md

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:

scheme A + scheme B = both required

Across multiple Security Requirement Objects:

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:

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.