Authentication for REST requests

[EnriqueL8]

What would you like to be added:
At the moment there is no notion of authentication within the spec when using a rest state. Let's assume we have a function such as

functions:
- name: secureAPI
  operation: "openapi.yaml#createPets"

The OpenAPI file might contain a security scheme such as Bearer Token. So how do I describe in my SW that I need to provide a bearer token for this request? One of the solutions might be to pass it in the argument for the functionRef but this isn't ideal since you would have to add it every time you want to use that function.

The best solution would be to have a new construct within the spec where you can define the different types of authentication for the functions being used. We can use the existing auth used to access the resource containing the function invocation information but in this case, it would be authentication information for the function invocation. Not saying we should use the same contract, but a have similar one for function invocation.

Why is this needed:
In order to describe the authentication needed a function invocation.

[cdavernas]

@EnriqueL8 you can use the top level auth property to define an authentication mechanism that you can reference in your function ref. It currently supports basic, oauth2 and bearer. I'd recommend using a secret-based OAuth2 auth definition so that you do not expose any sensitive info in your flow.
In Synapse, if an authRef is defined, we use it, should the OpenApi doc declare an auth mecanism or not.
Another option is to declare it as an expression-based arg in your function, and use the $SECRET reserved keyword not to expose anything sensitive

[EnriqueL8]

As far as I understood, the authRef is used to access the resource containing the function invocation information but not for authentication information at function invocation. I can't find anything in the functionRef for authentication.

Oh I do see it https://github.com/serverlessworkflow/specification/blob/main/specification.md#Function-Definition but this has to be predefined at creation and not workflow invocation

[cdavernas]

The authRef is used to reference an authentication mechanism declared at top level. The referenced scheme and its properties should be implemented and handled by the runtime when calling the function.
For example, if you referenced a basic auth definition, the runtime should, when calling an OpenApi function, add the appropriate Authorization header with the specified username and password.
Does that answer your question or am I missing smtg or failling to understand your use case?

[EnriqueL8]

So the use case is that at invocation time so when the workflow is started the user can provide some credentials that can then be used to perform the different states in the workflow instead of having predefined the username and password in a secret.

[cdavernas]

Well, but if you don't have an intermediate human task or a mechanism of the like, what would be the difference between pre-defining the username/password in an authDef or directly within the function?
You don't necessarily have to use a secret btw (but that would mean exposing your credentials in the workflow definition), you very well could do something like the following:

...
auth:
  - name: basic
    scheme: basic
    properties:
      username: serverlessworkflow
      password: rules
...

and reference it in your function like so:

functions:
  - name: MyFunctionWithBasicAuth
    type: rest
    operation: openapi.yaml#createPets
    authRef: basic

I would, however, advise against using such a scheme (basic or bearer), and would rather advise using oauth2. As a matter of fact, using the oauth2 scheme, the runtime would have to "produce" the token by contacting the configured authority, using the defined client_id, client_secret, etc, which is obviously way safer. You can find an example of an OAuth2 token generator here and a function implementation supporting authRef here

[EnriqueL8]

Yeah, OAuth is what @ricardozanini had suggested to me but instead of the client_id and api keys behind defined in the workflow they are passed through at invocation of the whole workflow.

So when the user wants to start the workflow they pass those credentials and then the runtime by looking at somewhere in the spec can correlate those to right function. Multiple users can use the same workflow but with their own credentials

[ricardozanini]

@cdavernas, the use case is an impersonation pattern for OAuth2, which means that the workflow will impersonate the user to make a call on their behalf. Of course, the SW must have a client_id and secret defined to generate the given token.

But the use case here, I believe, is to pass someway the user calling the flow to the OAuth2 process during runtime. It could be a header in the data payload, for instance. Or the spec could somehow describe how to do it per function definition (just thinking aloud).

In Synapse, if an authRef is defined, we use it, should the OpenApi doc declare an auth mecanism or not.

hmmm, I think there's a misconception here that we need to address in the spec then:

Auth definitions can be used to define authentication information that should be applied to resources defined in the operation property of function definitions. It is not used as authentication information for the function invocation, but just to access the resource containing the function invocation information.

If I interpreted this paragraph correctly, the authDef should not be used to invoke the function but rather the resource (the spec file) instead.

I'm +1000 to change the wording here and reuse the authDef for invocation.

[cdavernas]

@ricardozanini Ah, I missed that paragraph, which I did not write btw, though I did the auth PR. I always had in mind auth for both declaring doc and function invocation.
+1000 too to fix that misleading paragraph.

[ricardozanini]

@cdavernas, I'm sending a PR.

[fjtirado]

I would actually create two different structures, one called authCredentials, that contains the authorization information (client id and client secret for oauth2 client credential grant type, api key and api prefix for api, user and password for basic, token for bearer.. and authDef, that will contain the metadata information (the type of authorization: oauth2, apikey, basic, beared and metadata information for those ones that require it. token, refreshURL and grant type for oauth2, paramName and location for apikey).
Reason is that, when you have the open api definition, that metadata information defined by "new" authDef is in the open api file. So authRef needs to be specified, together with authCredentials, when protecting any uri (including legacy rest) while for openApi we just need authCredentials.
This reflect the difference of information needed between resources potentially protected (any external uri read by the flow, where you do not have any clue about the authorization type) and openapi invocations (where you know the authorization type and you need the credentials).
Besides, having two structure will allow us to include authCredentials and authRef where they are needed, becuase we still need to know if the auth information is intended to be applied to retrieve a URI or is intended to be applied as part of the function call. So, for example to specify that an openApi http uri requires auth to be read, we can use protectedResourceCredentials and protectedResourceDef optional fields indicating the required information, and for indicating that what is protected is the function call, we can just add a authCredentials in the function definition.

[fjtirado]

I forgot to mention than for gRPC or other function types different than OpenAPi, we will need an authDef. So, Im basically proposing to have four additional optional fields, which are specified as needed. If you want to protect both the spec file (gRPC, OpenApi...) and the function calls done thorugh this spec file, you will have as most 4 fields specified (three for OpenAPI)
Another option is to merge authCredentials and authDef in just one structure with two fields (one for credentials and one for def, def is only needed if the resource does not contain that info), so in the function definition rather than four you will have two fields, one to protect the resource and another to protect the function call.

[ricardozanini]

@cdavernas @tsurdilo what do you think about @fjtirado proposal? I will open a PR with the suggested changes, let me know if you have any comments.

[fjtirado]

Just an example of what I have in mind (using one structure for credentials and def)

Lets say we are calling an openapi service which definition file can be retrieved using basic authorization and which definition required oauth2 scheme to actually invoke the service

we will have

{
   "functions": [
      {
         "name": "HelloWorldFunction",
         "operation": "https://secure.resources.com/myapi.json#helloWorld",
         "resourceAuthRef": "My Basic Auth"  
         "invocationAuthRef": "My Oauth Auth"
      }
   ]
}

and then
{

auth: [
  {
    "name": "My Basic Auth",
     "schema" : "basic",
     "credentials": {
        "username" : "javierito",
        "password" : "${$SECRET.javierito.password}"
      } 
  }, 
  { 
   "name": "My Oauth Auth"
   "scheme": "Oauth2",
   "credentials": {
      "clientId" : "javierito",
      "clientSecret" : "${$SECRET.javierito.secret}"
   }
]
}

The rest of information for performing the oauth2 call will be on the open api definition. Now lets assume that we are not using openAPI and we want to include all the required info for oauth2. Then, we will use something like this for the oauth2 definition

  { 
   "name": "My Oauth Auth"
   "scheme": "Oauth2",
   "credentials": {
      "clientId" : "javierito",
      "clientSecret" : "${$SECRET.javierito.secret}"
   }, 
   "properties": {
     "grantType": "clientCredentials",
      "tokenURL": "https:www.givemethetoken.com/token",
      "refreshURL": "https:www.givemethetoken.com/refresh",
  }
}

If rather than Oauth2, we were using ApiKey scheme, then we will have

  { 
   "name": "My ApyKey Auth"
   "scheme": "ApiKey",
   "credentials": {
      "apiKey" : "${$SECRET.javierito.apiKey}",
   }, 
   "properties": {
     "location": "header",
      "key": "myApiKeyHeaderName",
  }
}

The poins it that properties must be completely omitted when you are using an auth def for an openapi call or any other call where scheme is already defined by the operation (so, for open api call, auth is a way to provide non fixed credentials information)