Azure Function Middleware

The Azure Function Middleware introduces a middleware pattern for Azure Functions in Node.js, enhancing the development experience by simplifying the integration of cross-cutting concerns such as schema validation, authorization, and error handling.

Installation

Before you integrate this middleware into your project, ensure you have Node.js installed, and you're familiar with Azure Functions. Follow these steps to set up:

npm install @senacor/azure-function-middleware

Usage

The middleware interface is intuitive, designed for expansion, and integrates seamlessly with Azure Functions. Here's a quick example to get you started:

import { HttpRequest, InvocationContext, app } from '@azure/functions';
import { AppInsightForHttpTrigger, middleware, requestBodyValidation } from '@senacor/azure-function-middleware';
import * as Joi from 'joi';

const httpHandler = async (request: HttpRequest, context: InvocationContext) => {
  context.info('function called');
  return { status: 201 };
};

const requestBodySchema = Joi.object().keys({
  name: Joi.string().min(3).max(30).required(),
});

app.http('example-function', {
  methods: ['POST'],
  authLevel: 'anonymous',
  route: 'example',
  handler: middleware(
    [AppInsightForHttpTrigger.setup, requestBodyValidation(requestBodySchema)], 
    httpHandler, 
    [AppInsightForHttpTrigger.finalize]
  ),
});

This pattern aims to deliver a core set of features and a simplified interface for creating additional middleware functions tailored for Azure Functions.

Error Handling

Centralized error management is a key feature, ensuring all errors within the function's flow are intercepted and appropriately handled. Specific error responses can be defined by throwing errors in the following format:

export class ApplicationError<T> extends Error {
  status: number;
  body?: T;
}

Any error thrown in the function with this signature is getting returned to the caller with the defined status and body.

Generic Functions

The middleware supports the integration of generic functions like request validation or authorization. These functions must comply with the 'AzureFunction' type from the '@azure/functions' package. They are crucial for extending the middleware's capabilities while adhering to Azure's function signature requirements.

Here is an example how you can write your own before and post execution functions:

import { HttpHandler, app } from '@azure/functions';
import { BeforeExecutionFunction, PostExecutionFunction, middleware } from '@senacor/azure-function-middleware';

export const httpHandler: HttpHandler = async (request, context) => {
  context.info('Function called');
  return { status: 201 };
};

const beforeFunction: BeforeExecutionFunction = (request, context, result) => {
  context.info('Called before httpHandler');
};

const postFunction: PostExecutionFunction = (request, context, result) => {
  context.log('Called after httpHandler');
};

app.http('test-validation-function', {
  methods: ['POST'],
  authLevel: 'anonymous',
  route: 'validation',
  handler: middleware([beforeFunction], httpHandler, [postFunction]),
});

First all beforeExecution functions are executed in the given order. Then the httpHandler is called and afterwards all postExecution are executed in the given order.

The Azure Function Middleware provides some useful before and post execution functions which are described in the following sections.

Request Body Validation

The function validates the request body based on a Joi Schema.

import { HttpHandler, app } from '@azure/functions';
import { middleware, requestBodyValidation } from '@senacor/azure-function-middleware';
import { ObjectSchema } from 'joi';
import * as Joi from 'joi';

export const httpHandler: HttpHandler = async (req, context) => {
  context.info('Function called');
  return { status: 201 };
};

const requestBodySchema: ObjectSchema = Joi.object({
  name: Joi.string().min(3).max(30).required(),
}).required();

app.http('example-function', {
  methods: ['POST'],
  authLevel: 'anonymous',
  route: 'example',
  handler: middleware([requestBodyValidation(requestBodySchema)], httpHandler, []),
});

By default, an ApplicationError with status 400 will be thrown and the httpHandler is not executed if the request body does not match the provided schema. There is an additional parameter to customize the behavior of requestBodyValidation (see requestBodyValidation.ts).

Request Query Params Validation

The function validates the request query parameters based on a Joi Schema.

import { HttpHandler, app } from '@azure/functions';
import { middleware, requestQueryParamsValidation } from '@senacor/azure-function-middleware';
import { ObjectSchema } from 'joi';
import * as Joi from 'joi';

export const httpHandler: HttpHandler = async (req, context) => {
    context.info('Function called');
    return { status: 201 };
};

const queryParamsSchema: ObjectSchema = Joi.object({
  name: Joi.string().valid('active', 'expired').optional(),
});

app.http('example-function', {
  methods: ['POST'],
  authLevel: 'anonymous',
  route: 'example',
  handler: middleware([requestQueryParamsValidation(queryParamsSchema)], httpHandler, []),
});

By default, an ApplicationError with status 400 will be thrown and the httpHandler is not executed if the query params do not match the provided schema. There is an additional parameter to customize the behavior of requestQueryParamsValidation (see requestQueryParamsValidation.ts).

Response Body Validation

The function validates the response body based on a Joi Schema.

import { HttpHandler, app } from '@azure/functions';
import { middleware, responseBodyValidation } from '@senacor/azure-function-middleware';
import { ObjectSchema } from 'joi';
import * as Joi from 'joi';

export const httpHandler: HttpHandler = async (req, context) => {
    context.info('Function called');
    return {
        status: 200,
        jsonBody: {
            name: 'John Doe',
        },
    };
};

const responseSchema: ObjectSchema = Joi.object({
    name: Joi.string().required(),
});

app.http('example-function', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'example',
    handler: middleware([], httpHandler, [responseBodyValidation(responseSchema)]),
});

By default, an error is logged if the response body does not match the provided schema. There is an additional parameter to customize the behavior of responseBodyValidation (see responseBodyValidation.ts).

Authorization

The authorization function verifies request parameters against JWT Bearer Tokens, employing customizable extraction functions for flexible security checks.

IMPORTANT: The signature of the JWT is not validated. Any well-formed JWT can be decoded (see jwt-decode).

import { HttpHandler, HttpRequestParams, app } from '@azure/functions';
import { jwtAuthorization, middleware } from '@senacor/azure-function-middleware';

export const handler: HttpHandler = async (req, context) => {
  context.log(`Function called by ${context.extraInputs.get('jwt')}`);
  return { status: 204 };
};

app.http('test-jwt-authorization-function', {
  methods: ['POST'],
  authLevel: 'anonymous',
  route: 'account/{accountId}',
  handler: middleware<HttpHandler>(
    [
      jwtAuthorization([
        {
          parameterExtractor: (parameters: HttpRequestParams) => parameters.accountId,
          jwtExtractor: (jwt: { sub: string }) => jwt.sub,
        },
      ]),
    ],
    handler,
    [],
  ),
});

The passed values in the array needs to be defined based on the following structure:

export type Rule<T> = {
    parameterExtractor: (parameters: HttpRequestParams) => string;
    jwtExtractor: (jwt: T) => string;
};

Header Authentication

To authenticate requests against a rule, the header could be used. Therefore, the headerAuthentication pre-function is available.

import { HttpHandler, app } from '@azure/functions';
import { headerAuthentication, middleware } from '@senacor/azure-function-middleware';

export const httpHandler: HttpHandler = async (req, context) => {
  context.info('Function called');
  return { status: 201 };
};

app.http('example-function', {
  methods: ['POST'],
  authLevel: 'anonymous',
  route: 'example',
  handler: middleware([headerAuthentication()], httpHandler, []),
});

When no parameter is passed to the headerAuthentication the header x-ms-client-principal-id is checked, if present or not. This header is added to a request by the Azure plattform when e.g. a JWT Token is successfully validated. The x-ms-client-principal-id and x-ms-client-principal-name header could only be set by the Azure plattform (https://learn.microsoft.com/en-us/azure/app-service/configure-authentication-user-identities).

It is also possible to pass a function to validate a specific header, like checking for basic authentication credentials. This could be done in the following manner headerAuthentication((headers: Headers) => boolean).

Logging and Tracing with Application Insights

To enhance the logging and tracing with appInsights you can wrap your function with the appInsightWrapper. Currently, this will add request parameters and workflow data into the customProperties, which will make your logs more searchable.

Use the AppInsightForHttpTrigger for your http-functions:

import { HttpHandler, app } from '@azure/functions';
import { AppInsightForHttpTrigger, middleware } from '@senacor/azure-function-middleware';

export const httpHandler: HttpHandler = async (req, context) => {
  context.info('Function called');

  return { status: 201 };
};

app.http('example-function', {
  methods: ['POST'],
  authLevel: 'anonymous',
  route: 'example',
  handler: middleware([AppInsightForHttpTrigger.setup], httpHandler, [AppInsightForHttpTrigger.finalize]),
});

and the AppInsightForNoNHttpTrigger for functions with different kinds of trigger (e.g. activityTrigger or timerTrigger).

Per default the request and response bodies of http requests are only logged if the request fails. You can customize this behavior by using AppInsightForHttpTrigger.finalizeWithConfig(...) instead of AppInsightForHttpTrigger.finalizeAppInsight. There you can also provide a function to sanitize the request and response bodies to prevent logging of sensitive data.

Support and Contact

If you encounter any issues or have questions about using this middleware, please file an issue in this repository or contact the maintainers at [email protected] or [email protected].