Skip to content

Reverse proxy header authentication

CloudBeaver offers a feature for authorization and authentication using reverse proxy headers. This method allows to authenticate users via specific HTTP header fields.

Important

Reverse proxy authentication trusts the configured HTTP headers. If users can access CloudBeaver directly or send these headers themselves, they can authenticate as any user. Expose CloudBeaver only through a properly configured reverse proxy.

Secure the reverse proxy

Before enabling reverse proxy authentication:

  1. Make sure CloudBeaver is reachable only through the reverse proxy. Do not expose its internal port or another network interface directly to users.
  2. Configure the reverse proxy to remove or overwrite all authentication headers supplied by the client before forwarding the request. Header names are case-insensitive. This includes the default headers X-User, X-Team, X-Role, X-Role-TE, X-First-name, X-Last-name, and X-Full-name. Remove any custom header names configured for the identity provider as well.
  3. Preserve CloudBeaver's CSRF protection. Do not configure authentication cookies with the SameSite=None attribute unless the deployment includes equivalent CSRF protection.

Configuration Steps

Enabling Reverse proxy authentication

  1. As an administrator, navigate to the Settings -> Server configuration.

  2. Locate the Reverse proxy option and activate this setting to allow reverse proxy authentication.

  3. Save changes.

Reverse proxy identity provider configuration in Community Edition

To configure reverse proxy authentication, follow these steps:

  1. Open your .cloudbeaver.runtime.conf configuration file.
  2. Locate the app section within the file.
  3. Add a new entry to the authConfigurations array with the following structure:
  "app": {
    ...
    "authConfigurations": [
      {
        "id": "your_proxy_id",
        "provider": "reverseProxy",
        "displayName": "your_proxy_username",
        "disabled": true,
        "iconURL": "",
        "description": "",
        "parameters": {
          "logout-url": "https://link_if_needed",
          "user-header": "",
          "team-header": "",
           "team-delimiter": "",
           "first-name-header": "",
           "last-name-header": "",
           "auto-user-provisioning": true
         }
       }
     ]
  }

Important

Ensure you include the mandatory fields id, provider, and displayName. The provider name must be set to reverseProxy.

Reverse proxy identity provider configuration

To configure reverse proxy authentication in the CloudBeaver using the graphical user interface (GUI), follow these steps:

  1. Log in as an administrator.
  2. Navigate to Settings -> Server configuration in the CloudBeaver interface.
  3. Click on the + Add button to create a new authentication provider.
  4. In the Provider dropdown menu, select Reverse Proxy.
  5. Enter a unique identifier in the ID field and a name for the configuration in the Configuration name field.
  6. Enable Auto-create users to create a CloudBeaver user automatically when a user logs in for the first time. If you disable this option, only existing users can log in.
  7. Click on Save to apply the changes.

reverse proxy provider creation

Configuring default HTTP header fields

Configure the standard HTTP header fields as follows:

Header Description
X-User user login
X-Team user teams
X-First-name user profile firstname
X-Last-name user profile lastname
X-Full-name user profile fullname
X-Role deprecated header for user teams

You can change the header names in the reverse proxy identity provider configuration. Remove or overwrite the custom names in the reverse proxy as well.

Header example

Consider a user named newuser, belonging to both user and admin teams. To access an application with reverse proxy header authentication enabled, the following HTTP headers should be set in the request to the CloudBeaver application:

X-User: newuser
X-Team: user|admin
X-First-name: John
X-Last-name: Smith

Tip

CloudBeaver categorizes users into two default teams: user and admin. Default delimiter used to separate teams in the header is | (could be customized in team-delimiter parameter, all characters are allowed).