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:
  securityRequirements:
    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.

[SensibleWood]

@baywet @handrews @lornajane just reflecting the discussion on TDC today, we'd look at using a registry to add a source of truth for the "approved" security profiles

[SensibleWood]

A few notes following on from the TDC meeting.

Expanded Design Notes

One of the gaps in the ecosystem alongside loosely coupled profiles such as that proposed is "joining up" what a security scheme is and what operations get invoked. I was therefore thinking there is value in adding another optional parameter here called "Supported Operations" that points to the canonical definitions of what Authorization Server operations (or their equivalent in non-OAuth 2.0 profiles) can look like.

To be clear: This points to an OpenAPI description which defines the example Authorization Server operations.

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

Then in the Security Requirement object - now rechristened "Security Profile Requirement Object", again thinking on naming because this is so much better than Doris, Gertrude or Sebastian - a JSONPath indicates the correct operation to be invoked.

The "Supported Parameters Schema" still provides the source of truth for the parameters, because I think there needs to be loose coupling between the canonical definition of the operations and the parameters, to make for reuse across different operations and avoid having a one-to-one relationship between a Security Profile Requirement Object and an Operation Object in supportedOperations.

component:
  securityProfileRequirements:
    AccountConsentClientCredentials:
      securityScheme:
        $ref: "#/components/schemas/BrasilOpenFinanceProfile"
      supportedOperation: "$.paths['/auth/1.0/token'].post"
      token_endpoint_auth_methods:
        - private_key_jwt
      grant_types:
        - client_credentials
      scopes:
        - account-information-consent:write
        - account-information-consent:read

Pros for this kind of thing:

• Needs: Addresses ecosystem need to tie together security definitions with a view of "what they look like" from a shape of the API perspective.
• Single version of the truth: You get security requirements and their API shape in one place in the OpenAPI description being consumed.
• Flexibility: The Supported Operations thing works well for providers who can point to something, but this could be omitted where not defined.

Cons:

• Opaque x 2: An OpenAPI description within a OpenAPI description is obviously already a thing due to External References, but this might be a bit "meta". It'd be interesting to see the take from a tooling maker on it.
• Arazzo anyone?: Feels a bit Arazzo-ish, but that is only a vague feeling.

Registry

@baywet brought up the registry requirement, which I'd thought of but not written down in the initial idea.

As the OpenAPI Specification we'd look to register name in the Security Scheme Object above, but this could have multiple permutations:

• fapi-20-security-profile: The core profile, looked after (potentially, ideally) by the FAPI WG.
• brasil-fapi-security-profile: The profile for Open Finance Brasil, looked after by Open Finance Brasil.
• uk-fapi-security-profile: The profile for UK Open Banking... (you get the point)

OR Brasil and UK just use fapi-20-security-profile and then add their own supportedParametersSchema and supportedOperations when they publish their standards.

Key points here:

• Ecosystem can go centrally, and register many profiles at the appropriate OAI registry.
• Ecosystem can go more decentralized, and reuse one profile many times, with market level configuration.

The nice thing is OAI doesn't need to decide this, its for the ecosystems involved to the right thing with the guardrails we set.

[handrews]

@SensibleWood more later, but regarding:

Arazzo anyone?: Feels a bit Arazzo-ish, but that is only a vague feeling.

I have actually previously proposed a type: arazzo Security Scheme that would allow folks to experiment with as much flexibility as they want. Although the OAS needs some improvements to really be able to connect up how authorization servers work. The necessary improvements are related to the overall SAF work.

[handrews]

@SensibleWood let me see if I have this correct:

The type: profile Security Scheme:

• names the base profile (with a name that can be registered)
• provides a set of servers that host the relevant metadata, which is assumed to match the named profile
• provides a schema that further restricts the profile, with names truncated to read more as parameters
• optionally provides an OpenAPI Description of the auth server

The Security Profile Requirement:

• names the security scheme
• provides values for the parameter-ish restricted sets described by the schema, including scopes
• points to a single operation for the interaction necessary to retrieve the credentials

Is this correct? I want to make sure before I start commenting further.

[SensibleWood]

Is this correct? I want to make sure before I start commenting further.

@handrews correct

[handrews]

@SensibleWood The fundamental idea of defining / refining profiles of existing standards is excellent.

I do have some questions and concerns about the specifics, and also maybe want to split this up a bit as it is trying to do a lot at once. A lot of those things are relevant to other security approaches (or even beyond that), and I want to make sure we take those into account. We already know that the existing Security Scheme approach is inadequate, so we'll be doing more in this area than just adding a type: profile Security Scheme.

TL;DR: This is the right direction, and I am mostly (aside from some confusion about the auth server OAD usage) convinced that it does what you want for the example that you have given. But I think there are a lot of details that need to be considered and shown to work before we can move forward with anything more concrete.

NOTE: The remainder of this comment has been moved to individual threads below, each with a large heading, except for the Servers comment which has been moved to issue #2284)

[handrews]

@SensibleWood

As there is a lot here I will chip away at it a comment at a time. Already I see the frailty of GitHub Discussions for tracing this kind of thing 🤷 but anyhoo.

Yeah... I'm going to do what I should have done in the first place and copy each of my comment sections to a new thread, and copy each of your replies to the appropriate thread, and then we can go from there. I'll hide these big comments once that's done to keep the focus on the individual threads. Apologies for the added email spam and having to copy and credit your replies.

The one exception will be the servers discussion, which I've moved to issue #2284.

[handrews]

Restricting profiles

I want to push back a bit on using a JSON Schema here (although see other threads for more on where a schema might still be useful).

My sense of the metadata files is that they already define an "interface" in the sense of specifying what options are supported, which means that any usage has to pick a specific option from each list. The examples above seem to fit with that, and seem to just further constrict the lists.

I am assuming that there is some software out there already that knows how to read the metadata formats and enable selection from the available lists. Making the OAS use a JSON Schema here introduces an additional technology, and one that is best suited to validating a specific input, and notoriously difficult for defining an interface. Parsing a JSON Schema to determine what might constitute a valid instance in advance is highly non-trivial. We already have some wording limiting how much schema parsing is necessary to do in other contexts, becasue without those limits it's just prohibitively difficult.

So my question is, why not just use a JSON Merge Patch value to constrain the metadata, and then let whatever existing software knows how to process metadata handle that without bringing a JSON Schema into the mix?

We would need to think about how to handle a merge-patch that expands a supported list, as that seems pathological, but if the original metadata is accurate, then attempting to expand it would just fail when the expanded value was used, so maybe that problem takes care of itself.

[handrews]

@SensibleWood's initial response:

I'm not sure what you mean here.

The JSON Schema is intended to provide a list of allowed parameters for a given Security Profile Requirement, and nothing more, in a relatively simple format that allows the Security Profile author to embed the requirements without needing OAS to explicitly state all of them.

In the very limited example above the parameters grant_type, token_endpoint_auth_methods, and scopes are telling the Client that understands the Security Profile what it needs to "provide" and "do" to access the operation.

The semantics are described by the Security Profile Provider, which then achieves the loose coupling principle.

Can you please provide a specific concrete example of how the proposed JSON Merge Patch approach would work?

[handrews]

@SensibleWood now I am not sure I understand what is going on here well enough to answer your quesiton about JSON Merge Patch, or even whether that is the right idea.

My assumption is that we are starting with an OIDC discovery document, and that the schema is related to that discovery document. To make this fully concrete, can you provide an example OIDC discovery document that would be used with this schema? Or if my assumption is not correct, what is the relationship between the OIDC discovery document and the schema?

[handrews]

Authorization Server OAD

I agree that there are ambiguities in authorization server interactions, but I am a bit skeptical of solving this with an OAD for the auth server. I am a fan of the idea of enabling auth workflows through Arazzo, but that's more of a "I have a weird experimental new thing and there's no other way to handle it" escape hatch.

What are the things that this auth server OAD is supposed to be clarifying? The example just referendes an operation but doesn't show how that actually works. I know that in some OAuth flows, information can be sent or returned in any of several different places. Is the OAD supposed to clarify that?

If so, how is that expected to work? I don't think OAS 3.2 can describe things in sufficient detail. I think we need to see a full example of this to understand what is going on.

[handrews]

@SensibleWood

The JSONPath is a pointer to the Operation Object or Workflow Object

Why JSONPath? Everything in the OAS uses JSON Pointer and I don't see why we would need something different here.

[SensibleWood]

Why JSONPath? Everything in the OAS uses JSON Pointer and I don't see why we would need something different here.

Largely I am ambivalent - I go with what I know - however Arazzo supports both, Overlay all JSONPath. Fundamentally "a thing to point to a thing is fine" as long as a) people understand the thing and b) its easy to write the thing 🤷

[handrews]

@SensibleWood Sounds good. If the TSC wants to add JSONPath as a dependency for OAS I'm fine with it. As you note, it's already in our ecosystem. I just want to use the least complex tool for the job. I tend to think of JSON Path only for situations where you want multiple selection, or might not know the exact location. I'd probably prefer operationId or workflowId here as it's more robust, but they have their issues as well.

[SensibleWood]

If you think OAS 3.2 is sufficient, I would like to see an example of that. As things stand, I think there is significant work to do on the OAS and on Arazzo before this can really be viable.

@handrews that was not and never was the point of the examples.

Both are supposed to show general approaches to dealing with RAR and what Token operations look like (and also a Discovery operation). Neither are complete, because OAS does not serve them well enough to make them feature complete. The do, however, provide humans with much more information on the shape of the security operations vs. the converse approach which is "do nothing".

It is clear that OAS needs underpinning work to make these viable, which (IMHO) is largely underpinning the operations with some standards JWT functionality.

As we move into more detailed work I suggest we need to deal with the Security Profile feature vs. cross cutting concerns like JWT handling separately.

[handrews]

@SensibleWood

Both are supposed to show general approaches to dealing with RAR and what Token operations look like (and also a Discovery operation). Neither are complete, because OAS does not serve them well enough to make them feature complete.

That is... exactly the point I'm trying to make? So I'm confused now. Are you or are you not arguing for the use of OADs/Arazzo documents as executable representations of the auth interaction steps? If you are, then the fact that the OAS/Arazzo is not capable of supporting such a thing is a major concern that we need to sort out before this can work. If you are not, then what are the OAD/Arazzo documents doing?

In the Thursday TDC calls, we have discussed that the current landscape requires automatable security processes, and that the old "good enough for someone to preconfigure an option in an interactive docs drop-down" is no longer sufficient. That's the context for me with all of this. We're trying to make this stuff automatable.

is largely underpinning the operations with some standards JWT functionality.

I think there's a good bit more to it than that. Selecting information out of a URL in a redirect to pass to another step, for example. Also, whatever is going on with the application/json vs application/x-www-form-urlencoded thing that I do not currently understand.

As we move into more detailed work I suggest we need to deal with the Security Profile feature vs. cross cutting concerns like JWT handling separately.

Right now I need to be convinced that whatever "cross cutting concerns" this proposal needs to be resolved in order for it to work are well-understood, and that we think we can address them alongside this proposal. Otherwise, what is the point of the proposal? Perhaps I am misunderstanding what constitutes a dependency here? I'm not saying we should sort our how to model JWTs or whatever in this discussion. But I do want to understand whether that feature (and others) are dependencies for this proposal, and how those dependencies fit together. Does that make sense?

[handrews]

Generic OAuth usage

What would it look like if we wanted to frame all OAuth configurations with this approach? Essentially defining an "empty" profile that allows whatever OAuth allows. Would that work? What would it look like? Or would we require everyone who wants to use OAuth to creae and register a profile before being able to use it?

[handrews]

@SensibleWood's initial reply:

Implementation: Both (see below)

To chop this up

What would it look like if we wanted to frame all OAuth configurations with this approach? Essentially defining an "empty" profile that allows whatever OAuth allows.

I don't think OAuth allows an "empty profile", because there needs to be metadata that describes the Authorization Server endpoints, token endpoints, etc. analogous to the existing Server Metadata approach and the OAuth Flow object properties.

Or would we require everyone who wants to use OAuth to creae and register a profile before being able to use it?

No because that would be a breaking change, and I don't see a good reason to wipe away OAuth Flow objects and go to v4.0 to facilitate Security Profiles.

However, we could create a Security Profile that honours baseline RFC 6749 and describe the baseline RFC 8414 if there was feedback from the community that was useful, and improved upon the existing OAuth Flow objects. The two can live side-by-side until such time as we need to deprecate it.

In my opinion this is the most reasonable approach, both from the perspective of evolving the Security Profile proposition and from avoiding a v4.0 for anything other the need for a really important breaking change.

[handrews]

@SensibleWood

I don't think OAuth allows an "empty profile", because there needs to be metadata that describes the Authorization Server endpoints, token endpoints, etc. analogous to the existing Server Metadata approach and the OAuth Flow object properties.

Ah, my intention with "empty profile" did not come across. Currently, we can already reference OAuth2 or OIDC metadata documents, so my assumption is that a "profile" is an additional layer on top of those that makes them less ambiguous. e.g. if the metadata allows many different ways of using it, the profile restricts it to a subset. So an "empty profile" would just mean using the metadata as is, with no further restriction.

Perhaps that is not the right way to think about it, please let me know if there's a better mental model here.

No because that would be a breaking change, and I don't see a good reason to wipe away OAuth Flow objects and go to v4.0 to facilitate Security Profiles.

We're not wiping away the existing Security Schemes, but they're inadequate for modern use cases so we are only retaining them for compatibility purposes. We already know that we need to build new OAuth, OIDC, etc. security mechanisms in 3.3, and I don't plan on attemptint to salvage the Security Scheme and OAuth Flow Objects as they are horribly confusing with all of the overloading. I expect we'll build some new thing alongside them (as with your Security Profile Requirements alongside old-style Security Requirements). I expect the type: profile Security Scheme would be done as one of these new things, but honestly it doesn't matter at this stage as you're mostly ignoring existing Security Scheme stuff.

That doesn't mean that the profile-based approach necessarily has to encompass all new-style OAuth/OIDC/GNAP usage, but I'd like to understand where the boundaries are. What can't (or shouldn't) be handled in the profile approach? That will tell us what other work we need to do in 3.3.

However, we could create a Security Profile that honours baseline RFC 6749 and describe the baseline RFC 8414 if there was feedback from the community that was useful, and improved upon the existing OAuth Flow objects. The two can live side-by-side until such time as we need to deprecate it.

Yes, that's what I'm trying to understand. What does that look like? That also provides a base for understanding how using a more specific profile differs from the general case. And we already know this is needed- the inability to fully automate OAuth and OIDC is a major driving factor for OAS 3.3 that we've discussed a good bit in the Thursday TDC calls.

[handrews]

Inputs

The schema currently being used to restrict the metadata also defines which things require inputs (although as noted above I think this can be done without the compelxity of a schema). But is it only metadata-listed values that are needed for inputs? Are there inputs needed around the auth server OAD usage? Or any other ambiguities that would need to be clarified at the point of use? If so, where are they handled?

This probably becomes more important if we are looking at supporting arbitrary OAuth usage where, to the extent that there is a "profile" at all, it is specific to the single API.

[handrews]

@SensibleWood's initial response:

Implementation: Abstract.

I think this is encapsulated in my comments here i.e. the shape of request/response bodies for security operations that support a Security Profile are described in an OAD or Arazzo document.

[handrews]

@SensibleWood What's unclear to me are what things need to be defined as inputs through a schema (see #5304 (comment)) vs not, and how those interact with any Arazzo workflow or OAD single operation. Could you make that a bit more concrete? Or is this something where we need to figure out how those inputs get routed to the workflow or operation? Just selecting the operation would not seem to be sufficient to me.

[handrews]

HTTP Auth and other interactions

Sometimes it is possible to use different HTTP Auth schemes in the context of OAuth (e.g. bearer vs DPoP). This is true in GNAP as well, where the options are GNAP or (with some caveats) bearer). How does this show up in the profiles approach? Do profiles sometimes leave this choice to the API designer?

My preference is that whether you are using HTTP Auth on its own or in the context of frameworks like OAuth and GNAP, it should look the same (as much as possible). This might require thinking through what we wnat HTTP Auth usage to look like in general (the current type: http Security Scheme is completely inadequate).

Similar interaction concerns might exist for mTLS and other mechanisms that can be used either on their own or as part of a framework.

[handrews]

@SensibleWood's initial response:

Here I think is where the most discussion and decision making is required.

IMO 3 approaches:

1. Everything is abstracted to the Security Profile and its metadata. No Security Requirements are reused from the core OAS. The Security Profile author must adopt the relevant semantics for describing HTTP Auth, Bearer tokens, etc. and describes that in the profile.
2. We reuse some Security Schemes where they exist and it is feasible to do so.
3. We embedded every choice in "first class" Security Schemes.

My preferred approach: 1 all the way. As soon as you start trying to cross the line between a Security Profile and existing objects you 1) start to taint the existing objects with a tonne of requirements and 2) increase the maintenance overhead for OAS hugely.

The job of OAS should be to state the preferred semantics of how a Security Profile describes HTTP Auth et al and set the guardrails, and then Security Profile authors do the rest. This achieves the loose coupling principle and allows OAS and security profiles to evolve at their own pace.

[handrews]

@SensibleWood your option 1 sounds good philosophically, but what does that mean? What if I want to use HTTP Authentication (no OAuth, OIDC, or GNAP) with the bearer scheme and a JWT token of a particular format?

Or, how do I express using the DPoP scheme rather than bearer with OAuth? The OAuth metadata can indicate that DPoP is supported. Does this then become an input parameter of some sort in the schema?

and then Security Profile authors do the rest

It's just not clear to me how Security Profile authors do this, and how generic tooling understands that this is what it needs to do.

[handrews]

GNAP

I want to make sure that this profile approach works for GNAP as well, so that we can see if it makes sense for metadata-driven frameworks in general. I don't necessarily need for this to be totally agnostic about OAuth vs GNAP vs whatever; it might make sense to have separate OAuth-by-profile or GNAP-by-profile systems. But they should be conceptually and (where possible) syntactically consistent.

[handrews]

@SensibleWood's initial response:

I don't have any specific concerns for how GNAP will work in the context of a Security Profile, given that almost the first interaction is that the AS must be advertised and described to allow negotiation to take place. I call out particularly Resource Access Rights and the abstraction to an OAD or Arazzo document as being a key feature of enabling GNAP support and will quote this from the last paragraph in that section:

"The exact mechanisms for relating reference strings is up to the API designer. These are enforced by the AS, and the details are out of scope for this specification."

The Security Profile can set the guardrails, the Security Profile Requirement sets the specific requirements for resource access, then the GNAP profile itself describes any underlying behaviours. This again sets out to meet the loose coupling principle.

In thinking on this further I wonder if there is an opportunity for an inline reference or local reference to a Path Item here, or just to a Schema Object that describes the Resource Access Rights Object. Just thinking out loud really.

[handrews]

Rich Authorization

Some OAuth profiles require the use of Rich Authorization Requests (RAR), which were developed alongside GNAP's largely compatible authorization system. How does this fit into the profile approach? My understanding is that this is an alternative to the traditional OAuth scopes approach that we support today, and that it is even possible to use both at once.

[handrews]

@SensibleWood's initial response:

Implementation: Abstract.

I know RAR very well, from designing the objects for the UAE open finance framework.

The answer is largely contained in here i.e. Security Profiles brings together the Security Requirement with a description of the RAR elsewhere. This is generally implemented within PAR based on my knowledge/experience to date, allow some GCC profiles use an Intent Lodging pattern to register the "RAR" first (certainly what UK Open Banking does).

Anyhoo, supporting RAR needs to be abstracted, referenced by the Security Profile, as OAS is simply not the place to define RAR objects.

[handrews]

@SensibleWood

OAS is simply not the place to define RAR objects.

Where do they belong, then? And what I really mean by that is "how does OAS tooling know that RAR is in use and take advantage of it" rather than "where is the exact interaction modeled" (although the latter question is also of interest).

[SensibleWood]

And what I really mean by that is "how does OAS tooling know that RAR is in use and take advantage of it"

That's the job of Security Profile, to point to the RAR objects that must be defined as Schema Objects/JSON Schema (it would make no sense to do anything else other than use existing approaches that make sense).

The exact mechanism for signalling "this is a RAR" I don't know yet, but what is already seen in the differences between PAR and GNAP there needs to be some generic mechanism (this is the gist of the supportedOperation feature above, but it needs more legs than that).

[handrews]

@SensibleWood

That's the job of Security Profile

I think I need to see exactly what a Security Profile is and (as noted below) understand exactly who is implementing what, and how.

My understanding is that there would be a registration of the profile that includes some sort of information to guide implementors beyond just the 3rd-party specification such as the FAPI 2.0 Security Profile.

• If that is correct, what goes in our registry?
• If that is not correct, and the 3rd-party specification is all we get for the profile, how is that supposed to work? My impression is that even FAPI 2.0 doesn't nail every single thing down.

At a conceptual level, this proposal makes sense. But I am struggling to understand what code I would write, and where I would put it (OAS implementation, FAPI-specific library, API-specific library, application code, wherever) to support this.

[handrews]

Separation of concerns

With your Security Profile Requirement Object (SPRO), it seems like you have shifted the boundaries somewhat.

Current Security Scheme Objects (SSOs) are just used as-is by Security Requirements, with at most a selection of which scope(s) apply. There's no need to $ref a Security Requirement Object (SRO) because there's hardly anything to it. I suppose it might be useful if you had a huge list of scopes, but that's the only use case I can think of.

But the SPRO fills out the details of your type: profile SSO, meaning that the type: profile SSO is not usable as-is. What was the rationale for this division? How much do you envision people making and using multiple different SPROs based on a single SSO?

[handrews]

@SensibleWood's initial response:

Security Profile Requirements are just a blown out version of a Security Requirement based on my perception of avoiding a breaking change.

Specifically though, the SPROs listed are designed provide abstractions of the requirements for a given resource.

I showed a Client Credentials grant type with scopes. This could easily be replaced by an Authorization Code grant type, or CIBA, or Hybrid flow (in reference to other point).

That's the point - list what is required for access using the metadata described in the schema. Then, make SPRO part of the Components Object to make them reusable across many Operation Objects.

[handrews]

@SensibleWood

Specifically though, the SPROs listed are designed provide abstractions of the requirements for a given resource.

So you see them as resource-specific, but potentially shared across many resources via $ref. While I think this probably works, we need to think a bit on how it is a change from how security requirements are more-or-less inherited from the top level. Selecting a Security Scheme by component name also has a different usage pattern than selecting by URI (which was only added in 3.2). We need to make sure we understand whether a fully $ref-to-URI approach will solve things as well as the inheritance or ref-by-name mechanisms. I don't know the answer here, making everythign $ref-to-URI is certainly simpler.

[handrews]

Modeling credential contents

There have been quite a few requests for modeling credential contents of various sorts. How would that fit in with this proposal? (and yes, I'm aware that some of them are supposed to be opaque, but people use the OAS for different purposes, sometimes more implementation-related and sometimes more interface-related).

Many things in the JOSE suite have their own media type, so we can model them with a Media Type Object. The question is where to put the model?

[handrews]

@SensibleWood's initial response:

This problem obviously transcends the Security Profile proposal, because the existing HTTP Auth support for it is low. Maybe we need a Credential Object, which can reference a Schema Object, with a bunch of standardised semantics?

[handrews]

@SensibleWood I agree that this should likely be split out, and indeed there are existing proposals such as the New Security Definitions proposal from @whitlockjc (discussion at OAI/sig-security#3) which in fact proposes a Credential Object. With that one, I think we would avoid regular expression usage in the Value Getter Object and build that sort of value selection more on Arazzo, runtime expressions, and better data models for things like the Authorization header.

But all of that could impact how this proposal works as well, particularly regarding any sort of OAD or Arazzo document for auth interactions- as seen above, there are other things where our value parsing/passing support is inadequate. So I think figuring this out is a prerequisite to truly model the needed interactions with Arazzo.

[handrews]

@SensibleWood taking a bit of a step back, I think I do not fully understand exactly who does what (apologies if some of this has been answered and I just missed it, I figure it's good to collect this in one place anyway):

• What, exactly, goes in a profile? Meaning, what does a PR to add a profile to our registry look like?
• Who is expected to write profiles? Only other standards organizations, or anyone that wants to use "new-style" OAuth/OIDC/whatever security modeling?
• What tools consume profiles? OAS implementations? OAuth or OIDC implementation libraries? Are they expected to be able to consume any arbitrary profile from machine-readable information, or are tools expected to write a custom implementation of each profile?
• If generic OAS implementations are not the primary consumer of tools, what are they expected to implement to support this?
• Are generic Arazzo tools expected to be able to process any workflows involved, or is there some expectation of customized tooling?