multi-auth

Accepts any one of several authentication plugins.

Category AuthenticationAdd it to Route, Service, Global rule, Plugin configEngine plugin multi-authPriority 2600

What it does

multi-auth lets a route accept any one of several authentication plugins, for example an API key for key-auth or a signed token for jwt-auth. Each entry under Auth plugins is one plugin with its own settings. The credentials stay where each plugin keeps them, on a consumer as its credentials.

A request that one of the plugins admits passes as the consumer that plugin found and reaches the backend. A request that none of them admits is answered 401 with Authorization Failed. Authentication shows how consumers and credentials fit together.

When to use it

• Moving clients from API keys to signed tokens: while the move lasts, a route accepts both, and older versions of the mobile app keep sending their key.
• One route serves partners that sign their requests with hmac-auth and internal tools that send an API key.
• People open a route in a browser with a username and password through basic-auth, while scripts call the same route with an API key.

Not for letting only some of the admitted consumers through — see consumer-restriction (Allows or denies requests by consumer, group, route or service) or a route where every client holds the same kind of credential — see key-auth (Authenticates consumers with an API key sent in a header or query parameter).

Set it up

Accept either an API key or a signed token

Fill Auth plugins as in the JSON below.

multi-auth · as the console saves it

{
  "auth_plugins": [
    {
      "key-auth": {
        "header": "x-api-key"
      }
    },
    {
      "jwt-auth": {
        "header": "authorization"
      }
    }
  ]
}

Things to know

• Auth plugins — With key-auth reading x-api-key and jwt-auth reading authorization, a request with the key or with the token is answered 200. A request with neither is answered 401 with Authorization Failed.
• A consumer signs in through each listed plugin with that plugin's own credential: a key for key-auth, and a key with a secret for jwt-auth.
• Auth plugins — The list is tried until one plugin admits the request, and each configuration is checked against that plugin's own schema while this one is written.
• Auth plugins — A plugin that does not authenticate, echo for example, is refused when you save.
• Auth plugins — A setting the named plugin's own form refuses is refused here too: a key-auth header that is a number cannot be saved.
• Your backend receives the consumer's username in X-Consumer-Username, whichever of the listed plugins admitted the request.
• AdviceList first the plugin most clients use, since the list is tried until one plugin admits the request.

Settings

The fields as the console shows them, section by section.

Auth pluginsauth_pluginsarray of objectsRequired

At least two entries, each an auth plugin's name holding its settings, as in {"key-auth": {}}. A plugin that does not authenticate is refused, and so is a setting that plugin's own schema refuses.

at least 2 items; each at least 1 key · example [{"key-auth":{"header":"x-api-key"}},{"basic-auth":{"realm":"g8 gateway"}}]

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.