Reverse proxy header authentication

Table of contents

• Secure the reverse proxy
• Configuration Steps
  • Enabling Reverse proxy authentication
  • Reverse proxy identity provider configuration in Community Edition
  • Configuring default HTTP header fields
  • Header example

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.

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).