Confusion around Authentication Schemes Flows

[alukach]

In the Authentication Schemes object, we have flows described as Map<string, (OAuth2 Flow Object|Signed URL Object)>. I interpret that as a mapping between a string and either the OAuth2 flow object or Signed URL object.

However, in the Scheme Definition examples, we have the oauth2 example written as such:

authentication/README.md

Lines 127 to 137 in faa9897

	"auth:schemes": {
	"oauth": {
	"type": "oauth2",
	"description": "requires a login and user token",
	"flows": {
	"authorizationUrl": "https://example.com/oauth/authorize",
	"tokenUrl": "https://example.com/oauth/token",
	"scopes": {}
	}
	}
	}

In ☝, the flows object appears to be a OAuth2 Flow Object, not a mapping of a string to the OAuth2 Flow Object.

Reviewing the signedUrl scheme type example, we do see a mapping:

authentication/README.md

Lines 181 to 212 in faa9897

	"auth:schemes": {
	"signed_url_auth": {
	"type": "signedUrl",
	"description": "Requires an authentication API",
	"flows": {
	"authorizationCode": {
	"authorizationApi": "https://example.com/signed_url/authorize",
	"method": "POST",
	"parameters": {
	"bucket": {
	"in": "body",
	"required": true,
	"description": "asset bucket",
	"schema": {
	"type": "string",
	"examples": "example-bucket"
	}
	},
	"key": {
	"in": "body",
	"required": true,
	"description": "asset key",
	"schema": {
	"type": "string",
	"examples": "path/to/example/asset.xyz"
	}
	}
	},
	"responseField": "signed_url"
	}
	}
	}

However, in ☝ I'm confused about the meaning of authorizationCode. Does it relate the the oauth2 authorization code flow (which happens to be omitted from the example)?

Additionally, it seems likely that the endpoint that performs URL signing would also require authentication. It seems like this is what authorizationCode could be relating to, but I would find that to be a strange way of modeling a flow's requirements.

It seems as though:

1. The flows type should simply be OAuth2 Flow Object|Signed URL Object, not a mapping. If this is correct, then calling it flows rather than flow feels a bit strange.
2. The signedUrl scheme should include support for its own auth:refs

If this is correct, then I suppose a complete signedUrl example could look like the following:

"auth:schemes": {
  "signed_url_auth": {
    "type": "signedUrl",
    "description": "Requires an authentication API",
    "flows": {
      "authorizationApi": "https://example.com/signed_url/authorize",
      "method": "POST",
      "parameters": {
        "bucket": {
          "in": "body",
          "required": true,
          "description": "asset bucket",
          "schema": {
            "type": "string",
            "examples": "example-bucket"
          }
        },
        "key": {
          "in": "body",
          "required": true,
          "description": "asset key",
          "schema": {
            "type": "string",
            "examples": "path/to/example/asset.xyz"
          }
        }
      },
      "auth:refs": ["oauth"],
      "responseField": "signed_url"
    },
    "oauth": {
      "type": "oauth2",
      "description": "requires a login and user token",
      "flows": {
        "authorizationUrl": "https://example.com/oauth/authorize",
        "tokenUrl": "https://example.com/oauth/token",
        "scopes": {}
      }
    }
  }
}

Thanks for the work done on this spec so far! It feels much needed.

[alukach]

@jamesfisher-geo @m-mohr Any input on ☝? I feel like I may be missing something...

[m-mohr]

I don't have the time right now to look into details, but it seems this was introduced here: #31

Additionally, the flows should be exactly as in OpenAPI except that we allow the SignedURL Object in addition to the OAuth Flow (not: Flows) Object: https://spec.openapis.org/oas/v3.1.0.html#security-scheme-object

So it looks like Map<string, (OAuth2 Flow Object|Signed URL Object)> is correct and the schema should follow this.

[alukach]

Additionally, the flows should be exactly as in OpenAPI except that we allow the SignedURL Object in addition to the OAuth Flow (not: Flows) Object: https://spec.openapis.org/oas/v3.1.0.html#security-scheme-object

This is helpful context, thanks. I've put together #42 to clear up the issue on the example.

I do think there's more to discuss regarding whether flows makes sense for "type": "signedUrl", but perhaps that belongs in an issue of its own.

[m-mohr]

The signed URL flows were introduced for things like getting the token for Microsoft Planetary Computer assets for example, but I haven't seen that being used in practice yet.

[alukach]

I was going to create another issue, but perhaps we can keep the convo going here: does it actually make sense to support multiple flows for a signedUrl? Do the keys of those flows have any actual meaning?

[m-mohr]

I guess it doesn't, but it was the simplest way to extend the mechanism that we inherited from OpenAPI.