Underspecified authorization property in workflows

[kezike]

The workflow creation endpoint expects a string value for authorization, but the response from this endpoint (as well as the response from the workflow retrieval endpoint) is specified as an object.

I suspect that both should be an object, but please correct me if I am wrong. If a string is expected, I imagine it would specify a particular authorization scheme. If so, what would those values be?

Also, does the description of "Authorization scheme information (e.g., OAuth2 configuration)" suggest that the OAuth 2 configuration would be the issuer's Oauth2 discovery document or is this something? What would this property look like for other authorization schemes?

[dlongley]

Yes, the authorization field is mis-specified at the moment as a string, it should be an object. How much we want to specify there (so that implementations agree) is a matter of debate.

An example from an implementation today looks like this:

authorization: {
  oauth2: {
    issuerConfigUrl: <oauth2 authorization server issuer configuration URL, i.e., '.well-known/...'>
  }
}

The above indicates that the workflow should use the above OAuth2 Authorization Server Issuer configuration URL to get the configuration for the OAuth2 Authorization Server Issuer it is to trust to issue oauth2 access tokens.

As for other authorization schemes, implementations today use either zcaps or OAuth2 -- and zcaps do not require any additional configuration other than the controller property in the workflow configuration. OAuth2 seems to be configurable with just the above issuer configuration URL to get its discovery document (aka "server metadata"). The spec probably doesn't need to specify anything else, but it can leave authorization open for extension by implementations and possible future specification if enough implementations do something else interoperably.

[msporny]

The group discussed this on the 2025-02-25 telecon:

@kezike noted that this property is underspecified. @dlongley agreed and noted that we could fully define it or leave some of it unspecified/flexible. @msporny suggested that we should at least provide examples, but if we could more fully define it, that would be good.

A PR should be raised that talks about the authorization field, and its an object, and if you're doing oauth2, that certain fields are required (server metadata URL) and how they are specified (linking to the section about scopes in the VC API spec /and/ the RFC detailing how you do OAuth2 authorization).