Why does Membrane API Gateway return 401 Unauthorized with Basic authentication?

The basicAuthentication plugin found no valid HTTP Basic credentials in the request. The Authorization header is missing or malformed, the user is unknown, or the password is wrong.

How do I hide the details in Membrane error responses?

Enable production mode by adding a configuration document with production: true to your apis.yaml. Membrane then leaves out detailed information from error responses.

401 Unauthorized: Basic Authentication Failed

Q: How do I send Basic credentials to Membrane?

Send the header Authorization: Basic followed by the Base64 encoding of username:password, for example with curl -u alice:secret.

Membrane API Gateway returns 401 Unauthorized when the basicAuthentication plugin finds no valid HTTP Basic credentials in a request. The request is rejected in the request flow and never reaches the backend.

The Error Response

The response contains the status 401 Unauthorized, the title Unauthorized, the problem type https://membrane-api.io/problems/security and a link to this page. It also carries the headers WWW-Authenticate: membrane and Connection: close. The type security means that a security plugin refused access to the API.

How Basic Authentication Works

The client sends the header Authorization: Basic followed by the Base64 encoding of username:password. The plugin decodes it and checks the pair against its users or a user data provider such as htpasswdFileProvider, jdbcUserDataProvider or ldapUserDataProvider.

api:
  port: 2000
  flow:
    - basicAuthentication:
        users:
          - username: alice
            password: qwertz
  target:
    url: https://api.predic8.de

api:
  port: 2000
  flow:
    - basicAuthentication:
        users:
          - username: alice
            password: qwertz
  target:
    url: https://api.predic8.de

Common Causes

The Authorization Header Is Missing

The client did not send credentials at all. Browsers only send them after a prompt; scripts and API clients must be configured to send them.

The Header Is Malformed

The Authorization header does not use the Basic scheme (for example it contains a Bearer token), its value is not valid Base64, or the decoded value has no : between username and password.

Wrong Username or Password

The username is unknown, or the password does not match. Remember that usernames and passwords are case-sensitive.

The User Data Provider Failed

If an external provider cannot verify the credentials, for example because the htpasswd file, the database or the LDAP server is unreachable, Membrane logs a warning and counts the attempt as a failed login.

How to Fix It

Client: send Authorization: Basic <base64 of username:password> with valid credentials, for example curl -u alice:qwertz http://localhost:2000.
Operator: check the users configured on basicAuthentication or in its user data provider.
Operator: check the log for warnings from the provider, and check that the file, database or LDAP server is reachable.

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem. These details may reveal information about your setup. In production, turn them off:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---.