Proposal: Supporting Loose-Coupling in Security Schemes and Security Requirements Objects

[SensibleWood]

The OpenAPI Specification provides a number of Security Scheme objects that are, largely speaking a "point in time" view
of a security requirement.

Take OAuth Flow Objects for example. OAuth Flow objects create a description of the security requirements for invoking given Operation that requires providing static properties that may not duplicate properties from the source of truth for the OAuth implementation. This duplication creates an inherent risk of drift, with security properties being updated in two places, with the OpenAPI view of OAuth often often much less rich than say - for example - OAuth Server Metadata.

Security Scheme Objects therefore potentially create a tight coupling between a given Operation Object (or the entire API description) and a snapshot of the OAuth configuration for that Operation. This approach served older versions of the OpenAPI Specification adequately enough, but the evolution of the security space and the creation of profile-based OAuth and OpenID Connect specification, such as the FAPI 2.0 Security Profile, has resulted in a significant gap between what the OpenAPI Specification can describe, and what such security profiles need to describe to API consumers.

This proposal therefore suggest a way forward on unlocking the means to describe security profiles in a suitably deterministic and loosely coupled way that provides API consumers with the affordances required to accurately understand the security requirements for a given Operation.

Note that this proposal addresses extension to key areas, namely OAuth Server Metadata and OpenID Connect Discovery
Metadata (hereafter Profile Metadata). The suggested changes are, however, seen as suitably extensible to accommodate
other profile-based API security approaches in the future.

Principles

Like any good proposal (well you can be the judge of that) some core principles provide useful context for understanding
the design approach.

The table below outlines said principles.

#	Principle	Rationale
1	Extensions for security profiles are loosely coupled.	Provides a close association between the OpenAPI Specification and external security standards that require minimal maintenance.
2	Security profile properties are described by metadata.	Aligned with #1, again to avoid tight coupling between OpenAPI Specification and external security profiles.
3	Multiple security constraints can be enforced based on profile abstraction, avoiding the need to directly include them in the OpenAPI Specification.	Avoids enforcing reuse of existing Security Requirement objects where reuse may create greater friction

Proposed Changes

Taking these principles as a guide (or maybe just some context) the proposed changes are provided below as building
blocks, to show progression from the most coarse-grained object to the most fine-grained.

This approach is taken to hopefully provide a persuasive view of the proposed changes.

Extensions to the Security Scheme Object

The first step is to extend the capabilities of the Security Scheme Object, to provide a comprehensive view of
Profile Metadata. Given this is aimed at v3.3, and is thus a non-breaking change, the approach is to introduce these
alongside existing OAuth and OpenID Connect objects.

The snippet below provides an example of the proposed change (with objects inline for clarity).

components:
  securitySchemes:
    BrasilOpenFinanceProfile:
      type: profile
      profileMetadata:
        name: fapi-20-security-profile
        schema: https://examples.openapis.org/brasil-fapi20-profile-schema.json
        servers:
          - name: Development
            url: https://examples.openapis.org/dev/.well-known
          -  name: Production
            url: https://examples.openapis.org/prod/.well-known

Note that this could use the Servers Object, but this is ignored right now for simplicity.

To annotate the example:

• A new type is introduced called profile, which indicates a security scheme based on an external source of
  metadata.
• profileMetadata then provides the metadata describing the profile, namely:
  • The name of the profile, to provide a clear indicator of what it is and an indicator of a canonical set of rules for
    apply or adhering to API security.
  • The schema that describes the profile metadata, in this case a schema describing OAuth Server Metadata or OpenID
    Discovery data.
  • A list of servers that resolve the required discovery at runtime. This expands on the previous openIdConnectUrl
    parameter significantly, and represents a more accurate representation of OpenID deployments, where multiple
    discovery operations are hosted (and it makes sense to provide for them all, not just - yes Overlays, but lots of
    organizations aren't there yet).

The job here for OpenAPI is not to provide a canonical view of the profile in its entirety, but instead to provide
enough "pointers" that allow API consumers to establish a source of truth.

Key to this mechanism is the schema property, which provides the attributes addressable in this profile. The utility
of this is leveraged in a revised Security Requirement object.

Profile Schema

The Profile Schema is a new feature that provides the "glue" between an external profile and what is described in
OpenAPI.

The design intention here is simple: Avoid the need to encode, and therefore maintain, every attribute from an external
security profile. Anecdotally many community members would agree that extending API security mechanisms in the OpenAPI
Specification is a good idea, but with a small team of active contributors there is a need to think more widely, so that
components of the specification can be loosely coupled, and maintained as separate artifacts.

OpenAPI does, of course already incorporate many other established standards, but where we reference RFCs or other
artefacts they tend to be slow moving and relatively straightforward to track. API security is complex, with many
properties, and security profiles are often edited (and frankly, well understood) by similarly small teams.

The loosely coupled approach is therefore intended to address both technical ownership and community needs.

A non-normative example of a JSON Schema that describes OpenAPI Discovery data (which may well exist in the wild - and
all the better if it did) is as follows. In this example OpenID Discovery metadata properties are truncated to -
removing the _supported suffix - to provide concrete lists of what is enforced in a given Security Requirement. For
the avoidance of doubt, the properties in question are grant_types_supported, token_endpoint_auth_methods_supported,
and scopes_supported.

PLEASE NOTE - THIS IS AN EXAMPLE AND PROVIDED TO MAKE A POINT. PLEASE DO NOT TEAR TOO BIG A HOLE IN IT.

$id: https://examples.openapis.org/brasil-fapi20-profile-schema.json
$schema: https://json-schema.org/draft/2020-12/schema
type: object
required:
  - grant_types
  - authentication_types
  - scopes
properties:
  grant_type:
    $ref: "#/$defs/GrantTypes"
  token_endpoint_auth_methods:
    $ref: "#/$defs/AuthenticationTypes"
  scopes:
    $ref: "#/$defs/Scopes"
$defs:
  GrantTypes:
    type: string
    enum:
      - authorization_code
      - client_credentials
  TokenEndpointAuthenticationTypes:
    type: string
    enum:
      - tls_client_auth
      - private_key_jwt
  Scopes:
    type: string
additionalProperties: false

Extensions to the Security Requirement Object

The new profile-based Security Scheme is therefore intended to significantly "unlock" what a Security Requirement can
provide, by simply referencing attributes of the profile stated in the schema.

The following is an example of a Client Credentials grant type, protected only by a JWT-based Client Assertion, and
based on the JSON Schema example above.

security:
  - ClientCredentials:
      securityScheme:
        $ref: "#/components/schemas/BrasilOpenFinanceProfile"
      token_endpoint_auth_methods:
        - private_key_jwt
      grant_types:
        - client_credentials
      scopes:
        - account-information-consent:write
        - account-information-consent:read

Each of the properties in the example Security Requirement are correlated with the profile metadata, and described by the
schema in profileMetadata. Here there is only one mandatory property, securityScheme which provides the reference
to the Security Scheme object that defines the metadata.

However, ideally this would actually be a Reference Object, with a new Security Requirement Component Object added to the
Component Object:

components:
  AccountConsentClientCredentials:
    securityScheme:
      $ref: "#/components/schemas/BrasilOpenFinanceProfile"
    token_endpoint_auth_methods:
      - private_key_jwt
    grant_types:
      - client_credentials
    scopes:
      - account-information-consent:write
      - account-information-consent:read

Evaluation

Again, like any good proposal, and especially the bad ones, this brings pros and cons.

On the pros side of the fence we get:

• Loose coupling: This approach allows adoption through a "plug-in" model, where we bring in Security Schemes that
  look after themselves. This could have neat side effects...
• Reducing maintenance overhead: Using a profile model allows teams of specialists to develop Security Schemes based
  on profiles (with appropriate guardrails) without relying on the core standards team, potentially increasing support
  across multiple security profiles. The TSC of course remains the arbiters of everything to do with final edits and
  merges, and the custodians of the enabling structure.
• "Implementer ignore": A profile view of the world could allow implementers to more readily "ignore stuff". A
  common complaint in the tooling ecosystem is tooling makers have to implement "everything". The profile model, when
  tailored around specific subject areas, provides places to ignore stuff.

On the cons there is:

• Opaque changes: Without some fairly specific guidance understanding profiles will be difficult to the layperson
  (in the sense of a layperson who knows about OpenAPI, of course).
• Incomplete model: Tooling makers may suffer picking up change from multiple sources (although OpenAPI would
  continue to the canonical source for all changes, and for the objects that enclose the model).

Next Steps

Let us discuss.

[handrews]

@SensibleWood great to see this proposal- I'm still digesting most of it, but I did want to ask a question about:

Extensions to the Security Requirement Object

The Security Requirement Object is currently a map where all values are arrays of strings (and the security field is an array of such Objects). This looks a like a map with all values as objects, which would seem less of a replacement and more of a redesign.

I'm not against a redesign, but I think we would have a new name and field for the resulting Objects so that people using the old system can continue to do so without confusion (as we did with adding the new in: querystring parameter location in 3.2 without dropping the old in: query option).

But I want to make sure I'm not misreading this.

[SensibleWood]

I'm not against a redesign, but I think we would have a new name and field for the resulting Objects so that people using the old system can continue to do so without confusion

Sounds good @handrews I'm happy with a new, side-by-side object - I used the description of Security Requirement largely for familiarity for anyone reading this - it can be new and called Doris, Gertrude, or Sebastian, as long as folks can make sense of what it is and what does.