Documentation

Authentication and Authorization in Mach5

Mach5 uses Keycloak to manage authentication and authorization, ensuring secure logins and access control for entities in the system.

Enabling Access Control In Mach5

To enable access control in Mach5, you need to set the oidc.enabled parameter in the values.yaml file. This activates authentication and authorization features, allowing the system to securely verify user identities and manage their access permissions.

The admin user credentials can be customized by setting the keycloak.master.username and keycloak.master.password parameters in the values.yaml file. By default, these values are set to admin/admin. Note: Any update in the master realm username/password from the Keycloak UI must also be reflected in the Mach5 Search helm deployment.

Setting up new users in Mach5

Follow these steps to log in as the administrator to be able to create new users:

  • Navigate to <MACH5_HOST>:<MACH5_PORT>/keycloak and log in using the admin credentials. By default, you’re logged into the master realm.

Keycloak Sign-up Page

  • Change the realm from the top left drop-down menu to default.

Changing to master realm

  • Once the realm is set to default, click on Users from the left-side menu to create new users.

Keycloak User Menu

  • Click on Create new user.

Create New User

  • Fill in the required fields and click on the Create button.

Add User Details in Keycloak

  • Once the user is created, navigate to its Credentials tab and click on Set password to assign credentials to the created user.

Keycloak Credentials Tab

  • Set the password for the user. Make sure to turn off the Temporary toggle button for the user. Save the credentials.

Setting user password

  • To assign access permissions to this user, add roles for this user by navigating to the Role mapping tab. Click on Assign role.

Role Mapping in Keycloak

  • Choose the Filter by realm roles filter from the drop-down. The list will now populate with all Mach5 access permission roles.

Filter by realm roles

  • Select the role(s) you want the user to have access to. Full access can be granted to a user by assigning the m5-admin role. Click on Assign.

Assign M5 Admin Role

  • User role mapping is updated for the user. You can view the list of permissions as shown below.

Role Selection in Keycloak

Log into Mach5

  • To log into Mach5, navigate to <MACH5_HOST>:<MACH5_PORT>/ and this will redirect you to the default realm login portal.

Mach5 Login Portal

  • Enter the user credentials. Click on Sign in.

Fill user credentials

  • On signing in successfully, you will now be able to access the Mach5 Data Explorer UI.

Mach5 Data Explorer UI

Logging out

  • To log out, go to <MACH5_HOST>:<MACH5_PORT>/logout.

Access permissions

Following are the roles available to be assigned to users:

  • m5-admin : Administrator role with full access
  • indices/create : Allow creation of indices
  • indices/read : Allow reading from all indices
  • indices/update : Allow updating all indices
  • indices/delete : Allow deleting all indices
  • indices/multiget/create : Allow multi get creation of indices
  • indices/multiget/read : Allow multi get search across indices
  • indices/multiget/update : Allow multi get update of all indices
  • indices/multiget/delete : Allow multi delete of indices
  • indices/setting/create : Allow applying index settings
  • indices/setting/read : Allow fetching settings for all indices
  • indices/setting/update : Allow updating index settings
  • indices/setting/delete: Allow removing index settings
  • indices/data/read : Allow search across all indices
  • indices/data/update : Allow data updates across all indices
  • indices/mapping/read : Allow fetching index mapping
  • indices/mapping/update : Allow updating index mapping
  • indices/alias/create : Allow creation of aliases for all indices
  • indices/alias/read : Allow reading all aliases
  • indices/alias/update : Allow updating all index aliases
  • indices/alias/delete : Allow deletion of aliases

Apart from the above roles, there are index-level roles for finer access control that can be done by assigning roles like:

  • index:<INDEX_NAME>/data/read
  • index:<INDEX_NAME>/data/update
  • index:<INDEX_NAME>/mapping/read
  • index:<INDEX_NAME>/mapping/update
  • index:<INDEX_NAME>/read
  • index:<INDEX_NAME>/setting/read
  • index:<INDEX_NAME>/setting/update
  • index:<INDEX_NAME>/update

Current Limitations

  • AuthZ is implemented to include and exclude Indexes in queries only when using the OpenSearch API
    • This path is also covered by the use of OpenSearch Dashboards
    • Use of Ingest Pipelines is currently not protected by AuthZ
    • Use of KQL through notebooks is currently not protected by AuthZ
  • Index level roles are not automatically created when an index is created
    • This has to be done manually in the Keycloak UI