Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OAuth Flow required fields + validation #2666

Closed
char0n opened this issue Aug 2, 2021 · 11 comments
Closed

OAuth Flow required fields + validation #2666

char0n opened this issue Aug 2, 2021 · 11 comments
Labels

Comments

@char0n
Copy link
Contributor

char0n commented Aug 2, 2021

Hi everybody,

I'm currently working on some tooling regarding OAS 3.0.0 and found a situation where I'd need some clarification. Spec defines OAuth Flow Object as an object with following fields required:

  • authorizationUrl
  • tokenUrl
  • scopes

This is crystal clear so far. Next I'm using JSON Schema provided in this repo to validate the OAS 3.0.0 definition. But looking into the JSON Schema document reveals that none of the OAuth Flow objects require above define fields to be required. Some OAuthFlow objects requires just one field, other two. I'm not sure if this is intended (for particular type of OAuth Flow to have only certain fields required) or this is something we should fixed.

Update
I completely missed Applies To column of OAuth Flow Object. That clarifies things out. But scopes are required in ImplicitOAuthFlow only, even though they should be required in all flow types. In this case is the spec or the JSON Schema the source of truth?

  ImplicitOAuthFlow:
    type: object
    required:
      - authorizationUrl
      - scopes
    properties:
      authorizationUrl:
        type: string
        format: uri-reference
      refreshUrl:
        type: string
        format: uri-reference
      scopes:
        type: object
        additionalProperties:
          type: string
    patternProperties:
      '^x-': {}
    additionalProperties: false

  PasswordOAuthFlow:
    type: object
    required:
      - tokenUrl
    properties:
      tokenUrl:
        type: string
        format: uri-reference
      refreshUrl:
        type: string
        format: uri-reference
      scopes:
        type: object
        additionalProperties:
          type: string
    patternProperties:
      '^x-': {}
    additionalProperties: false

  ClientCredentialsFlow:
    type: object
    required:
      - tokenUrl
    properties:
      tokenUrl:
        type: string
        format: uri-reference
      refreshUrl:
        type: string
        format: uri-reference
      scopes:
        type: object
        additionalProperties:
          type: string
    patternProperties:
      '^x-': {}
    additionalProperties: false

  AuthorizationCodeOAuthFlow:
    type: object
    required:
      - authorizationUrl
      - tokenUrl
    properties:
      authorizationUrl:
        type: string
        format: uri-reference
      tokenUrl:
        type: string
        format: uri-reference
      refreshUrl:
        type: string
        format: uri-reference
      scopes:
        type: object
        additionalProperties:
          type: string
    patternProperties:
      '^x-': {}
    additionalProperties: false

Thanks for any clarification to this!

@MikeRalphson
Copy link
Member

In this case is the spec or the JSON Schema the source of truth?

The markdown spec is always the source of truth.

Pinging @jdesrosiers for the meta-schema issue.

@jdesrosiers
Copy link
Contributor

I'm not too familiar with the 3.0 schema, but I'll take a look. Sounds like it's just missing a required somewhere.

@webron
Copy link
Member

webron commented Aug 9, 2021

The confusion might be from missing the Applies To column in the spec. The fields are only applicable to specific flows, and only if they are applicable they'd be required. That's why the different flows in the JSON Schema has different ones required for different flows (based on the aforementioned column).

@char0n
Copy link
Contributor Author

char0n commented Aug 10, 2021

I'm not too familiar with the 3.0 schema, but I'll take a look. Sounds like it's just missing a required somewhere.

@jdesrosiers I can issue a PR with JSON Schema conforming the to the spec.

The confusion might be from missing the Applies To column in the spec. The fields are only applicable to specific flows, and only if they are applicable they'd be required. That's why the different flows in the JSON Schema has different ones required for different flows (based on the aforementioned column).

@webron yeah might as well be. When I first reported this, I missed the Applies To as well. Then a minute later when I've discovered it I've appended another section labelled Update to the issue description.

@webron
Copy link
Member

webron commented Aug 10, 2021

That should teach me not to only read email notifications ;) Yeah, that should be a fairly simple fix, just add the scopes to the required list in the other workflows. Thanks, @char0n!

char0n added a commit to char0n/OpenAPI-Specification that referenced this issue Aug 10, 2021
This makes metaschema consistent with the 3.0.x spec.

Refs OAI#2666
@char0n
Copy link
Contributor Author

char0n commented Aug 10, 2021

Pull request has been issued against main branch: #2673

char0n added a commit to char0n/OpenAPI-Specification that referenced this issue Aug 11, 2021
This makes metaschema consistent with the 3.0.x spec.

Refs OAI#2666
char0n added a commit to char0n/OpenAPI-Specification that referenced this issue Aug 12, 2021
This makes metaschema consistent with the 3.0.x spec.

Refs OAI#2666
@OAI OAI deleted a comment Aug 18, 2021
webron pushed a commit that referenced this issue Aug 19, 2021
This makes metaschema consistent with the 3.0.x spec.

Refs #2666
@char0n
Copy link
Contributor Author

char0n commented Aug 26, 2021

After merging #2673 we've noticed that json and yaml schemas are now different (https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.0). According to the README the json should be generated but it wasn't. It can cause problems for anybody pulling the schema into their tool assuming that yaml and json versions are the same.

@MikeRalphson
Copy link
Member

@char0n thanks - I'm working on the GitHub action to regenerate and republish the schemas when they change but it has taken longer than expected. I'll raise a PR to resync manually.

@LasneF
Copy link
Member

LasneF commented Mar 22, 2024

@MikeRalphson , @jdesrosiers
there is may be a full resynch to do , as 3.0 is out of synch as well as 3.1

i would suggest to may be abandon the synch and keep only one source of truth
(preferably the Json one as more standard for tooling)

duplication of information is source of confusion and complication

@handrews
Copy link
Member

@LasneF we already have issues tracking the myriad problems with the schemas and their deployment. The should be included on in Automation & Infrastructure project and are just waiting for someone with time and inclination to sort it out.

BTW, we manually edit the YAML schema (because it's human-friendly) and then auto-generate the JSON one. In theory, anyway.

@handrews
Copy link
Member

Since the only problem here is the deployment and we have issues tracking that (see previous comment), I'm going to close this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

6 participants