Security

Security Overview: Authentication and Authorization

Beer Garden offers foundational authentication and authorization features for user and role management. This document explains how authentication and authorization function and outlines the available configuration options.

Note: These features are still developing, and user-friendly configuration methods may be limited.

Authorization Basics

Each API endpoint in Beer Garden requires a specific permission type. Before accessing or modifying data, users must pass an access check to ensure they possess the necessary permissions. Detailed information on permissions and their assignment is provided later, but the core principle is that access control is managed through these API permissions. The Beer Garden UI, brewtils Plugin, and EasyClient code all interact with these permissions via API calls.

Roles and Permissions

Beer Garden employs Role-Based Access Control (RBAC), where permissions are assigned based on user roles rather than individually. Roles are defined by a combination of permission types and scopes:

  • Permission Types include:

    • READ_ONLY: View Requests and System Status

    • OPERATOR: Execute Commands

    • PLUGIN_ADMIN: Admin actions for Plugins

    • GARDEN_ADMIN: Admin actions for Child Gardens

  • Scopes define the boundaries within which a role’s permissions apply, such as Gardens, Namespaces, Systems, Instances, Versions, and Commands. Permissions are filtered based on the scopes list, meaning users only have access within the specified scopes.

Scopes will filter records and their internal values. For example, if a role has a filter for Commands, only those commands will appear in the System record.

Authentication Basics

When authorization is enabled, users must authenticate to access Beer Garden. There are two primary methods:

  1. Web UI Access: A "login" button will appear at the top right of the page. Clicking this button brings up a login box where users can enter their credentials.

  2. API Access: Users send credentials via POST to /api/v1/token to receive access and refresh tokens. The access token is used in subsequent API calls via the Authorization: Bearer header. Both the Web UI and EasyClient handle this token-based workflow behind the scenes.

Authentication Settings

Authorization and authentication settings are housed under a top level auth section of the main application configuration yaml file. Some general information about the settings is below, but for the full list of configuration options check out the configuration guide.

Authentication Handlers

Authentication and authorization settings are located in the auth section of the main application configuration YAML file. Here’s a summary of available authentication handlers:

  • Basic: Username and password authentication.

  • Trusted Header: Authentication via headers set by a trusted proxy. If the garden is behind a proxy that authenticates users and adds their username to a header, this method enables the garden to use that header’s username.

  • LDAP: When a user attempts to log in, their provided credentials (username and password) are sent to the LDAP server. The server checks these credentials against its directory of user records. If the credentials match, the server authenticates the user and provides access; otherwise, the login attempt is denied.

Enabling trusted headers requires that users access the garden only through the proxy to prevent unauthorized direct access, which could allow users to falsify headers.

Default Admin Account: On initial startup, a default admin user with username "admin" and password "password" is created, along with a superuser role. This account’s credentials can be modified under auth. default_admin or through the "Change Password" option in the UI.

Defining Roles

Roles are groupings of permission types and scopes. They can be tailored to fit the functional needs of users. To define roles, use one of these methods:

  1. UI: Create roles directly in the User Admin UI.

  2. YAML File: Create a YAML file and set the auth.role_definition_file setting to its location. The file should list role definitions, including names, permissions, and scopes.

Example YAML Configuration:

- name: "garden_admin"
  permission: "GARDEN_ADMIN"

- name: "operator"
  permission: "OPERATOR"

- name: "read_only"
  permission: "READ_ONLY"

- name: "plugin_admin"
  permission: "PLUGIN_ADMIN"

- name: "System A - Operator"
  permission: "OPERATOR"
  scope-systems:
    - "System A"

You can also find an example in the example configs.

Upstream vs Local Role

Upstream Roles: Managed externally (e.g., by Parent Garden or an Authentication platform). These roles are unique to each user and are not recorded in the Roles Table. Changes to upstream roles for one user do not affect others.

Local Roles: Managed within Beer Garden. Modifications to a local role impact all users assigned to that role.

Defining Users

A User is defined by a combination of username, password, local roles, upstream roles, and alias mappings. Except for upstream roles, all values can be managed locally. There are two methods for managing user accounts:

  1. User Admin UI: Manage users directly in the UI.

  2. YAML File: Create a YAML file and set the auth.user_definition_file setting to its location. The file should include a list of user definitions with usernames, roles, and protection status.

Example YAML Configuration:

- username: "user1"
  roles:
    - "operator"

- username: "user2"
  roles:
    - "garden_admin"

- username: "user3"
  roles:
    - "read_only"

- username: "user4"
  roles:
    - "plugin_admin"
  protected: True

For additional examples, refer to the users.yaml file in the following link: :https://github.com/beer-garden/beer-garden/tree/develop/src/app/example_configs[example configs.]

Protected user accounts cannot be managed via the User Admin UI. Users always retain access to their own requests, even if their roles change, provided they have at least READ_ONLY permissions.
Passwords should not be stored in plain text in the YAML file.

Garden Alias User Mappings

For users with accounts across multiple Beer Gardens, alias mapping maintains traceability of requests. Requests forwarded to a Child Beer Garden are mapped to the Alias username, and requests received from a Child Beer Garden map back to the local Username. Alias mappings are managed through the User Admin UI.

Syncing User Permissions

Beer Garden syncs user accounts with Child Beer Gardens under two conditions:

  1. The user has alias mappings to the child garden.

  2. The child garden configuration enables shared_users.

Roles forwarded to Child Beer Gardens are filtered accordingly to what is within their operational scope.

Roles without scopes will be applied universally to all Child Gardens for affected user accounts.