Add a new authorization runtime expression argument

[cdavernas]

What would you like to be added:

Introduce a new authorization argument in runtime expressions.

Why is this needed:

This enhancement would enable tasks to utilize authorization credentials that have been resolved through a specified authentication process.

For instance, during an authenticated OpenAPI call, it may be necessary to pass the resolved authorization value (e.g., JWT token) as a parameter to the invoked operation.

This is especially important if the operation being called also needs to make further downstream API requests.

Additional information:

This feature was introduced in a previous Synapse release but wasn't backported to the specification. Some of our users require it for certain edge cases.

[cdavernas]

@bvandewe FYI

[cdavernas]

@JBBianchi @ricardozanini @matthias-pichler @fjtirado What do you guys think?

[ricardozanini]

This is a similar case in which we had to adapt our runtime.

We use a custom X-Auth header passed from the client and the token-exchange pattern to exchange tokens and pass them through to underlying calls. This way, the correct tokens are assigned and used to call external services. Internally, the headers govern where to send the token, depending on the service ID on the OpenAPI spec.

It would be nice to be able to define which authorization to use depending on the target service in the DSL. I'm curious to discuss this as we solve this issue here.

[cdavernas]

@ricardozanini the token exchange is indeed the proper way to go, but there are some edge cases where this feature is not applicable. For example, a legacy service hosted on, say, OpenFaas, and protected by basic auth. Said service might not have access to the calling requests headers, or might need to pass the authorization parameter to downstream services as a parameter other than the authorization header. Again, I'm speaking of edge/exotic use case support, which would be addressed by proposed argument.

[ricardozanini]

That's fine; I'd like to see this in the DSL, too, and discover new ways to make it easier for us to handle such authorization cases.

But in my scenario, the headers are managed by the runtime implementation. Based on the openApi/function name or id, the token is mapped to the correct service calls.

Having it in the DSL might facilitate a few things.

[fjtirado]

@cdavernas I think is a good idea, but can we add an example to discuss minor details?

[cdavernas]

@fjtirado Sure!

My proposal is to supply that argument with the following properties:

Name	Type	Description
scheme	string	The resolved authorization scheme. In case of bearer, oauth2 or oidc, this would be Bearer.
parameter	string	The resolved authorization parameter. In case of bearer, oauth2 or oidc, this would contain the generated access token. In case of basic, it would hold the base 64 encoded username:password concatenation.

Here's an example passing the authorization info resolved using the defined authentication to the protected downstream service:

document:
  dsl: '1.0.0-alpha5'
  namespace: examples
  name: pass-authorization-values-explicitly
  version: '0.1.0'
do:
  - callSecuredEndpoint:
      call: http
      with:
        endpoint:
          uri: https://mysecuredendpoint.com
          authentication:
            oidc:
              authority: https://mykeycloak.com
              client:
                id: test
                secret: super-safe-secret
              scope: api
          body:
            someParameter1: value1
            someParameter2: value2
            scheme: '${$authorization.scheme }'
            token: '${ $authorization.parameter }'