Http Functions

Routing

By default, when you create an HTTP triggered or WebHook function the function is addressable via a route of the form http://<yourapp>.azurewebsites.net/api/<funcname>. You can customize this route via the route property in your function.json file, e.g.:

{
    "bindings": [
        {
            "type": "httpTrigger",
            "name": "req",
            "direction": "in",
            "methods": [ "get" ],
            "route": "products/{category:alpha}/{id:int?}"
        },
        {
            "type": "http",
            "name": "res",
            "direction": "out"
        }
    ]
}

This function will be addressable via url http://<yourapp>.azurewebsites.net/api/products/electronics/123. This route also demonstrates support for route constraints. Documentation on the constraint formats supported can be found here.

In a C# function, you can then define parameters that bind to the route parameters like so:

public static Task<HttpResponseMessage> Run(
     HttpRequestMessage request, string category, int? id, TraceWriter log)
{
    ...
}

Here's the same function definition coded in Node.js, showing how the bound route parameter values can be accessed via context.bindingData:

module.exports = function (context, req) {
    var category = context.bindingData.category;
    var id = context.bindingData.id;

    ...
}

By default, all function routes will be prefixed with api. You can customize or remove that prefix entirely via the http.routePrefix property of host.json, e.g.:

{
    "http": {
        "routePrefix": ""
    }
}

Here we've set this to an empty string which means that no prefix will be used. So rather than https://<yourapp>.azurewebsites.net/api/<funcname> the default route for functions in the app will be http://<yourapp>.azurewebsites.net/<funcname>.

Authentication and Authorization

HTTP triggered functions support API key based athentication, where the API key is passed in one of the following ways:

• Query string: The key is passed as a query string parameter named code (e.g. https://<yourapp>.azurewebsites.net/api/<funcname>?code=<your api key>)
• Request header: Alternatively, you can pass your API key in a request header named x-functions-key

The following authorization levels are supported:

• Anonymous: No authentication is required. The function may be invoked without an API key.
• Function: Authentication is required and a function API key must be used.
• Admin: Authentication is required and the function can only be invoked with the admin (master) key

API Keys

To enable the authentication/authorization process

API keys are may be defined at two distinct levels:

• Host: Also commonly referred to as Function App Level keys. Keys defined at this level apply to the entire Function App. You have the ability to define Function Keys at this level, and they would allow clients to authenticate against any function. This is also where your Master Key is defined.
• Function: Function level keys apply to the specific functions they're defined under, restricting its use for authentication to that function only.

To enable key rolling and consumer specific keys, you can define multiple named keys at the host and/or function levels.

API keys are persisted, encrypted, on the file system under D:\home\data\Functions\secrets, in files matching the function name for function level keys, and a file named host.json for the host level keys.

Master Key

The master key provides administrative access to the runtime APIs. You should exercise care if you choose to use the Admin authorization level for your functions as we do not recommend redistributing the master key.

WebHooks

For WebHooks, authentication and authorization are handled by the WebHook receiver for the WebHook type you've selected (e.g. GitHub, Slack, etc.). By default, the key that is provided to the WebHook receiver is the default function key (named 'default'). If you want to perform validation using a different key, the WebHook provider should provide a client ID (the key name) in of the following ways:

• Query string: The client id is passed as a query string named clientid (e.g. https://<yourapp>.azurewebsites.net/api/<funcname>?clientid=<your key name>)
• Request header: Alternatively, the provider can pass the client ID in a request header named x-functions-clientid

NOTE: Keys defined at the function level take precedence over host level keys, so if a two keys are defined with the same name at the function and host level, the function key will be used.

Managing API keys

The primary way to manage API keys is through the Azure Functions portal.

In HTTP triggered functions, a key management panel is available in the portal, allowing you to manage (create, refresh and revoke) function and host level keys.

Key Management API

To support programatic key management, the host exposes a key management API. API documentation coming soon.