Skip to content

Resource and invocation authentication definition #643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 24, 2022
Merged

Resource and invocation authentication definition #643

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1f571cb
Added function resource and invocation authentication
cdavernas Jun 20, 2022
1c92eca
Minor fixes to the spec file
cdavernas Jun 21, 2022
90eb5a9
Added a note on how to handle auth def declared for an OpenAPI function
cdavernas Jun 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 26 additions & 3 deletions schema/functions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
60 changes: 53 additions & 7 deletions specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand All @@ -3266,6 +3265,55 @@ 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 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:

```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` 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.

```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
```

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 |
Expand Down Expand Up @@ -3483,10 +3531,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 |
| --- | --- | --- | --- |
Expand Down