From 1f571cba24e1d01aeb8c3c61cf031d5797b73e65 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Mon, 20 Jun 2022 18:09:44 +0200 Subject: [PATCH 1/3] Added function resource and invocation authentication Signed-off-by: Charles d'Avernas --- schema/functions.json | 29 ++++++++++++++++++++--- specification.md | 55 +++++++++++++++++++++++++++++++++++++------ 2 files changed, 74 insertions(+), 10 deletions(-) diff --git a/schema/functions.json b/schema/functions.json index 08f3b345..a29bd2d7 100644 --- a/schema/functions.json +++ b/schema/functions.json @@ -54,9 +54,32 @@ "default": "rest" }, "authRef": { - "type": "string", - "description": "References an auth definition name to be used to access to resource defined in the operation parameter", - "minLength": 1 + "oneOf": [ + { + "type": "string", + "description": "References the auth definition to be used to invoke the operation", + "minLength": 1 + }, + { + "type": "object", + "description": "Configures both the auth definition used to retrieve the operation's resource and the auth definition used to invoke said operation", + "properties":{ + "resource":{ + "type": "string", + "description": "References an auth definition to be used to access the resource defined in the operation parameter", + "minLength": 1 + }, + "invocation":{ + "type": "string", + "description": "References an auth definition to be used to invoke the operation" + } + }, + "additionalProperties": false, + "required": [ + "resource" + ] + } + ] }, "metadata": { "$ref": "common.json#/definitions/metadata" diff --git a/specification.md b/specification.md index 159ef389..51911ef2 100644 --- a/specification.md +++ b/specification.md @@ -1986,8 +1986,7 @@ If we have the following function definition: ``` The `authRef` property is used to reference an authentication definition in -the `auth` property and should be applied to access the `https://secure.resources.com/myapi.json` -OpenApi definition file. +the `auth` property and should be applied when invoking the `helloWorld` function. An [AuthRef](#AuthRef-Definition) object can alternatively be used to configure the authentication definition to use when accessing the function's resource and/or when invoking the function. The `functions` property can be either an in-line [function](#Function-Definition) definition array, or an URI reference to a resource containing an array of [functions](#Function-Definition) definition. @@ -3248,7 +3247,7 @@ Depending on the function `type`, the `operation` property can be: Defining custom function types is possible, for more information on that refer to the [Defining custom function types](#defining-custom-function-types) section. The `authRef` property references a name of a defined workflow [auth definition](#Auth-Definition). -It is used to provide authentication info to access the resource defined in the `operation` property. +It is used to provide authentication info to access the resource defined in the `operation` property and/or to invoke the function. The [`metadata`](#Workflow-Metadata) property allows users to define custom information to function definitions. This allows you for example to define functions that describe of a command executions on a Docker image: @@ -3266,6 +3265,50 @@ Note that using metadata for cases such as above heavily reduces the portability Function definitions themselves do not define data input parameters. Parameters can be defined via the `parameters` property in [function definitions](#FunctionRef-Definition) inside [actions](#Action-Definition). +###### AuthRef Definition + +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| resource | References an auth definition to be used to access the resource defined in the operation parameter | string | yes | +| invocation | References an auth definition to be used to invoke the operation | string | no | + +The `authRef` property references a name of a defined workflow [auth definition](#Auth-Definition). +It can be a string, in which case the referenced [auth definition](#Auth-Definition) is used solely for the function's invocation, or an object, in which case it is possible to specify an [auth definition](#Auth-Definition) to use for the function's resource retrieval (as defined by the `operation` property) and another for its invocation. + +Example of a function definition configured to use an [auth definition](#Auth-Definition) called "My Basic Auth" upon invocation: + +```yaml +functions: +- name: SecuredFunctionInvocation + operation: https://test.com/swagger.json#HelloWorld + authRef: My Basic Auth +``` + +Example of a function definition configured to use an [auth definition](#Auth-Definition) called "My Basic Auth" to retrieve the resource defined by the `operation` property, and an [auth definition](#Auth-Definition) called "My OIDC Auth" upon invocation: + +```yaml +functions: +- name: SecuredFunctionInvocation + operation: https://test.com/swagger.json#HelloWorld + authRef: + resource: My Basic Auth + invocation: My OIDC Auth +``` + +Note that if multiple functions share the same `operation` value, and if one of them defines an [auth definition](#Auth-Definition) for resource access, then it should always be used to access said resource. +In other words, when retrieving the resource of the function "MySecuredFunction2" defined in the following example, the "My Api Key Auth" [auth definition](#Auth-Definition) should be used, because the "MySecuredFunction1" has defined it for resource access. +This is done to avoid unnecessary repetitions of [auth definition](#Auth-Definition) configuration when using the same resource for multiple defined functions. + +```yaml +functions: + - name: MySecuredFunction1 + operation: https://secure.resources.com/myapi.json#helloWorld + authRef: + resource: My ApiKey Auth + - name: MySecuredFunction2 + operation: https://secure.resources.com/myapi.json#holaMundo +``` + ##### Event Definition | Parameter | Description | Type | Required | @@ -3483,10 +3526,8 @@ If `false`, both Event payload and context attributes should be accessible. ##### Auth Definition -Auth definitions can be used to define authentication information that should be applied -to resources defined in the operation property of [function definitions](#Function-Definition). -It is not used as authentication information for the function invocation, but just to access -the resource containing the function invocation information. +Auth definitions can be used to define authentication information that should be applied to [function definitions](#Function-Definition). +It can be used for both the retrieval of the function's resource (as defined by the `operation` property) and for the function's invocation. | Parameter | Description | Type | Required | | --- | --- | --- | --- | From 1c92eca02b97587c2a4623a649e946dd4ff82697 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Tue, 21 Jun 2022 10:31:33 +0200 Subject: [PATCH 2/3] Minor fixes to the spec file Signed-off-by: Charles d'Avernas --- specification.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/specification.md b/specification.md index 51911ef2..d3bda995 100644 --- a/specification.md +++ b/specification.md @@ -3272,8 +3272,11 @@ defined via the `parameters` property in [function definitions](#FunctionRef-Def | resource | References an auth definition to be used to access the resource defined in the operation parameter | string | yes | | invocation | References an auth definition to be used to invoke the operation | string | no | -The `authRef` property references a name of a defined workflow [auth definition](#Auth-Definition). -It can be a string, in which case the referenced [auth definition](#Auth-Definition) is used solely for the function's invocation, or an object, in which case it is possible to specify an [auth definition](#Auth-Definition) to use for the function's resource retrieval (as defined by the `operation` property) and another for its invocation. +The `authRef` property references a name of a defined workflow [auth definition](#Auth-Definition). It can be a string or an object. + +If it's a string, the referenced [auth definition](#Auth-Definition) is used solely for the function's invocation. + +If it's an object, it is possible to specify an [auth definition](#Auth-Definition) to use for the function's resource retrieval (as defined by the `operation` property) and another for its invocation. Example of a function definition configured to use an [auth definition](#Auth-Definition) called "My Basic Auth" upon invocation: @@ -3295,7 +3298,7 @@ functions: invocation: My OIDC Auth ``` -Note that if multiple functions share the same `operation` value, and if one of them defines an [auth definition](#Auth-Definition) for resource access, then it should always be used to access said resource. +Note that if multiple functions share the same `operation` path (*which is the first component of the operation value, located before the first '#' character*), and if one of them defines an [auth definition](#Auth-Definition) for resource access, then it should always be used to access said resource. In other words, when retrieving the resource of the function "MySecuredFunction2" defined in the following example, the "My Api Key Auth" [auth definition](#Auth-Definition) should be used, because the "MySecuredFunction1" has defined it for resource access. This is done to avoid unnecessary repetitions of [auth definition](#Auth-Definition) configuration when using the same resource for multiple defined functions. From 90eb5a98ad1b07e4cbc4288404bf2b44d76d9b4f Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Thu, 23 Jun 2022 10:31:26 +0200 Subject: [PATCH 3/3] Added a note on how to handle auth def declared for an OpenAPI function Signed-off-by: Charles d'Avernas --- specification.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification.md b/specification.md index d3bda995..2627a6f0 100644 --- a/specification.md +++ b/specification.md @@ -3312,6 +3312,8 @@ functions: operation: https://secure.resources.com/myapi.json#holaMundo ``` +It's worth noting that if an [auth definition](#Auth-Definition) has been defined for an OpenAPI function which's resource declare an authentication mechanism, the later should be used instead, thus ignoring entirely the [auth definition](#Auth-Definition). + ##### Event Definition | Parameter | Description | Type | Required |