basic-auth

Authenticates consumers with HTTP Basic credentials.

Category AuthenticationAdd it to Route, Service, Global rule, Plugin configEngine plugin basic-authPriority 2520Needs a Consumer with a basic-auth Credential

What it does

basic-auth asks the client for a username and password. They live on a consumer, as one of its credentials, under Username and Password. The plugin on the route reads them from the request's Authorization header in the Basic scheme, the one browsers and HTTP clients send. Authentication shows how consumers and credentials fit together.

A request whose username and password match a credential passes as that consumer and reaches the backend. A request without them is answered 401 with a WWW-Authenticate header that names your Realm, the name a browser shows in its sign-in prompt.

When to use it

• An internal dashboard behind the gateway that people open in a browser: the browser asks for a username and password and sends them with every request.
• A partner system that can send a username and password but cannot sign tokens or compute signatures.
• A backend that should not check passwords itself: the gateway checks them against your consumers, and only the requests that passed reach the backend.
• Several clients of one route, each with a username and password on its own consumer, so that plugins acting by consumer, a limit for example, tell them apart.

Not for an API key a client sends with each request — see key-auth (Authenticates consumers with an API key sent in a header or query parameter), signed tokens that expire or carry claims — see jwt-auth (Authenticates consumers with a JSON Web Token they present) or passwords kept in your company directory — see ldap-auth (Authenticates consumers against an LDAP directory).

Guides

Pages that walk through a job with basic-auth, step by step.

• Ask for a username and passwordPut basic-auth on a route so that a client signs in with a username and password, and a browser asks for them.

Set it up

Ask for a username and password before the request goes on

The username and password are those of a consumer's basic-auth credential.

Turn on Hide credentials and set Realm to Orders API.

The console's Add plugin panel, filled with this example.

basic-auth · as the console saves it

{
  "realm": "Orders API",
  "hide_credentials": true
}

What you will see

• A request without credentials is answered 401 and asks for them with WWW-Authenticate: Basic realm="Orders API", so a browser opens its sign-in prompt with that name.
• A request with the username and password of mobile-app is answered 200; the credentials are removed before the request reaches the backend, which receives X-Consumer-Username: mobile-app instead.
• A request with the right username and a wrong password is answered 401 with Invalid user authorization.

More scenarios

Give a consumer a username and password to sign in withcredential

Under Credential set Username to mobile-app and set Password to <secret>.

basic-auth credential · as the console saves it

{
  "username": "mobile-app",
  "password": "<secret>"
}

What you will see

• A request with this username and password is answered 200, and the backend receives the consumer's name in X-Consumer-Username.
• A request without credentials is answered 401 with Missing authorization in request.

Things to know

• With the plugin on a route and nothing set, a request whose Authorization header carries a credential's username and password is answered 200, and the same request without the header 401.
• Realm — Set to Orders API, a request without credentials is answered 401 with WWW-Authenticate: Basic realm="Orders API".
• Password — Avoid spaces and colons: the client's whitespace is stripped and its password is read up to the next colon, so such a credential never signs in.
• Anonymous consumer — It takes a consumer's username: letters, digits, _ and -. A name with a dot in it is refused when you save.
• Anonymous consumer — While this names an existing consumer, a request with no credential or a wrong one passes as that consumer instead of being refused. A name that belongs to no consumer refuses them with 401.
• Your backend receives the consumer's username in X-Consumer-Username, so it tells clients apart without seeing the password.
• Hide credentials — On, the Authorization header that carried the username and password does not reach the backend.
• AdviceServe a route with basic-auth over HTTPS only, since every request it admits carries a password.

Settings

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

Hide credentialshide_credentialsbooleandefault false

Realmrealmstringdefault basic

The name the client's sign-in prompt shows, sent in WWW-Authenticate on every 401. No double quotes or backslashes.

1 to 128 characters ·

pattern

^[ -!#-[\]-~]+$

Anonymous consumeranonymous_consumerstring

at least 1 character · letters, digits, hyphens and underscores up to 256 characters, or a $secret:// or $env:// reference

pattern

^([$]secret://.+|[$][Ee][Nn][Vv]://.+|[a-zA-Z0-9_-]{1,256})$

Credential

What each consumer's credential for basic-auth carries.

Credential

2 fields from the plugin's credential schema.

UsernameusernamestringRequired

PasswordpasswordstringRequired

The password the client sends together with this username. Stored on the engine and shown only to roles that manage this object.

at least 1 character

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