Azure Functions

This plugin invokes Azure Functions. It can be used in combination with other request plugins to secure, manage or extend the function.

Terminology

• plugin: a plugin executing actions inside IAM before or after a request has been proxied to the upstream API.
• Service: the IAM entity representing an external upstream API or microservice.
• Route: the IAM entity representing a way to map downstream requests to upstream services.
• Consumer: the IAM entity representing a developer or machine using the API. When using IAM, a Consumer only communicates with IAM which proxies every call to the said upstream API.
• Credential: a unique string associated with a Consumer, also referred to as an API key.
• upstream service: this refers to your own API/service sitting behind IAM, to which client requests are forwarded.

Configuration

This plugin is compatible with requests with the following protocols:

• http
• https

This plugin is compatible with DB-less mode.

Enabling the plugin on a Service

With a database

Configure this plugin on a Service by making the following request:

$ curl -X POST http://localhost:8001/services/{service}/plugins \
    --data "name=azure-functions"  \
    --data "config.functionname=" \
    --data "config.appname=AZURE_APPNAME" \
    --data "config.apikey=AZURE_APIKEY"

Without a database

Configure this plugin on a Service by adding this section do your declarative configuration file:

plugins:
- name: azure-functions
  service: {service}
  config: 
    functionname: 
    appname: AZURE_APPNAME
    apikey: AZURE_APIKEY

In both cases, {service} is the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

With a database

Configure this plugin on a Route with:

$ curl -X POST http://localhost:8001/routes/{route}/plugins \
    --data "name=azure-functions"  \
    --data "config.functionname=" \
    --data "config.appname=AZURE_APPNAME" \
    --data "config.apikey=AZURE_APIKEY"

Without a database

Configure this plugin on a Route by adding this section do your declarative configuration file:

plugins:
- name: azure-functions
  route: {route}
  config: 
    functionname: 
    appname: AZURE_APPNAME
    apikey: AZURE_APIKEY

In both cases, {route} is the id or name of the Route that this plugin configuration will target.

Enabling the plugin on a Consumer

With a database

You can use the http://localhost:8001/plugins endpoint to enable this plugin on specific Consumers:

$ curl -X POST http://localhost:8001/consumers/{consumer}/plugins \
    --data "name=azure-functions" \
     \
    --data "config.functionname=" \
    --data "config.appname=AZURE_APPNAME" \
    --data "config.apikey=AZURE_APIKEY"

Without a database

Configure this plugin on a Consumer by adding this section do your declarative configuration file:

plugins:
- name: azure-functions
  consumer: {consumer}
  config: 
    functionname: 
    appname: AZURE_APPNAME
    apikey: AZURE_APIKEY

In both cases, {consumer} is the id or username of the Consumer that this plugin configuration will target.

You can combine consumer_id and service_id

in the same request, to furthermore narrow the scope of the plugin.

Global plugins

• Using a database, all plugins can be configured using the http://localhost:8001/plugins/ endpoint.
• Without a database, all plugins can be configured via the plugins: entry on the declarative configuration file.

A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of IAM) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Note: If config.https_verify is set as true then the server certificate will be verified according to the CA certificates specified by the lua_ssl_trusted_certificate directive in your IAM configuration.

Demonstration

To demonstrate the plugin, set up the Azure Functions “hello world” function.

1. In this example we'll consider the following settings/placeholders, insert your own values here:

    - `<appname>` for the Functions appname
    - `<functionname>` for the function name
    - `<apikey>` for the api key
   

2. Test your function to make sure it works before adding it to IAM

    curl -i -X GET https://<appname>.azurewebsites.net/api/<functionname>?name=IAM \
         -H "x-functions-key:<apikey>"
   
    HTTP/1.1 200 OK
    ...
    "Hello IAM!"
   

3. Create a Service on IAM

    $ curl -i -X  POST http://localhost:8001/services/ \
      --data "name=plugin-testing" \
      --data "url=http://dead.end.com"
   
    HTTP/1.1 201 Created
    ...
   

4. Add a Route to the Service on IAM

    $ curl -i -X  POST http://localhost:8001/services/plugin-testing/routes \
      --data "paths[]=/mytest"
   
    HTTP/1.1 201 Created
    ...
   

5. Apply the Azure-functions plugin

    $ curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \
        --data "name=azure-functions" \
        --data "config.appname=<appname>" \
        --data "config.functionname=<functionname>" \
        --data "config.apikey=<apikey>"
   
    HTTP/1.1 201 Created
    ...
   
   

6. Test the Azure Function through IAM (same result as step 2)

    curl -i -X GET http://localhost:8000/mytest?name=IAM
   
    HTTP/1.1 200 OK
    ...
    "Hello IAM!"
   

In this example we're only passing a query parameter name to the Azure Function. Besides query parameters, also the HTTP method, path parameters, headers, and body will be passed to the Azure Function if provided.

Limitations

Use a fake upstream_url

When using the this plugin, the response will be returned by the plugin itself without proxying the request to any upstream service. This means that whatever url has been set on the Service it will never be used. Although url will never be used, it's currently a mandatory field in IAM's data model, so feel free to set a fake value (ie, http://dead.end.com as per the example above) if you are planning to use this plugin. In the future, we will provide a more intuitive way to deal with similar use cases.

Response plugins

There is a known limitation in the system that prevents some response plugins from being executed. We are planning to remove this limitation in the future.