Configuring Grafana Authentication

This topic describes how to configure different authentication methods for users to log in to the Grafana UI.

Overview of Grafana Authentication

In the Grafana Authentication pane, you configure how users log in to the Grafana UI.

By default, users log in to the Grafana UI using basic authentication. With basic authentication, all users log in to the Grafana UI using the username admin and the administrator login credentials found in the Credentials tab of the Healthwatch for VMware Tanzu tile.

However, you can configure the Grafana UI to use another authentication method alongside or instead of basic authentication. This allows users to use their own credentials to log in to the Grafana UI.

The sections in this topic describe how to configure different authentication methods for users to log in to the Grafana UI:

Basic authentication. For more information, see Configuring Basic Authentication below.
Generic OAuth, UAA, or LDAP. For more information, see Configuring Other Authentication Methods below.

The values that you configure in the Grafana Authentication pane also configure their corresponding properties in the Grafana configuration file. For more information, see Overview of Configuration Files in Healthwatch in Configuration File Reference Guide, Grafana Authentication in Configuration File Reference Guide, and the Grafana documentation.

Configuring Basic Authentication

When you configure basic authentication for the Grafana UI, all users log in to the Grafana UI using the username admin and the login password found in the Credentials tab of the Healthwatch tile. If you disallow basic authentication, users cannot log in with administrator credentials.

To allow or disallow basic authentication, see one of the sections below:

Allow Basic Authentication
Disallow Basic Authentication

Allow Basic Authentication

To configure basic authentication and obtain the login password for the Grafana UI:

Navigate to the Ops Manager Installation Dashboard.
Click the Healthwatch tile.
Select Grafana Authentication.
Under Basic authentication, select Allow.
Click Save.
Select the Credentials tab.
In the Admin Login Password row of the Grafana section, click Link to Credential.
Record the value of password. This value is the password that all users must use to log in to the Grafana UI.

Disallow Basic Authentication

To disallow basic authentication:

Navigate to the Ops Manager Installation Dashboard.
Click the Healthwatch tile.
Select Grafana Authentication.
Under Basic authentication, select Do not allow.
Click Save.

Configuring Other Authentication Methods

You can configure the Grafana UI to use another authentication method alongside or instead of basic authentication. This allows users to use their own credentials to log in to the Grafana UI.

For example, if you want to limit the number of users who can log in to the Grafana UI with the Grafana administrator credentials found in the Credentials tab of the Healthwatch tile, but still allow non-administrator users to log in to the Grafana UI, you can configure one of the following authentication methods in addition to basic authentication:

Generic OAuth. For more information, see Configure Generic OAuth Authentication below.
User Account and Authentication (UAA). For more information, see Configure UAA Authentication below.
LDAP. For more information, see Configure LDAP Authentication below.

If you want to only allow users with Grafana administrator credentials to log in to the Grafana UI, you can configure the Grafana UI to use only basic authentication. For more information, see Configure Only Basic Authentication below.

Configure Generic OAuth Authentication

When you configure generic OAuth authentication for the Grafana UI, users can log in to the Grafana UI with their credentials for the Grafana-supported OAuth provider of your choice, including the UAA instance for a runtime on a different Ops Manager foundation. For more information about configuring generic OAuth authentication, see the Grafana documentation. For a list of Grafana-supported authentication integrations, see the Grafana documentation.

To configure generic OAuth authentication for the Grafana UI:

Navigate to the Ops Manager Installation Dashboard.
Click the Healthwatch tile.
Select Grafana Authentication.
Under Additional authentication methods, select Generic OAuth.
For Provider name, enter the name of your OAuth provider.
For Client ID, enter the client ID of your OAuth provider. The method to retrieve this client ID differs depending on your OAuth provider. To find the client ID of your OAuth provider, see the Grafana documentation.
For Client secret, enter the client secret of your OAuth provider. The method to retrieve this client secret differs depending on your OAuth provider. To find the client secret of your OAuth provider, see the Grafana documentation.
For Scopes, enter a comma-separated list of scopes that the OAuth provider adds to the user’s token when they log in to the Grafana UI. These scopes differ depending on your OAuth provider. To find the scopes for your OAuth provider, see the Grafana documentation.
For Authorization URL, enter the authorization URL of the server for your OAuth provider.
For Token URL, enter the token URL of the server for your OAuth provider.
For API URL, enter the API URL of the server for your OAuth provider.
For Logout URL, enter the URL to which users are redirected after logging out of the Grafana UI.
(Optional) For Email attribute, enter the attribute that contains the email address of the user. For more information, see the Grafana documentation.
For Grafana domain, enter the domain of the Grafana instance. You must configure this field if your OAuth provider requires a callback URL that uses the root URL of the Grafana instance. If your OAuth provider does not require a callback URL, do not configure this field.
(Optional) To allow new users to create a new Grafana account when they log in with their existing OAuth credentials for the first time, activate the Allow new accounts with existing OAuth credentials checkbox. This checkbox is activated by default. Deactivating this checkbox prevents users without a pre-existing Grafana account from creating a new Grafana account or logging in to the Grafana UI with their existing OAuth credentials.
(Optional) For Allowed domains, enter a comma-separated list of domains. Configuring this field limits Grafana UI access to users who belong to one or more of the listed domains.
For Allowed teams, enter a comma-separated list of teams. Configuring this field limits Grafana UI access to users who belong to one or more of the listed teams. Configure this field if your OAuth provider allows you to separate users into teams. If your OAuth provider does not allow you to separate users into teams, do not configure this field.
For Allowed organizations, enter a comma-separated list of organizations. Configuring this field limits Grafana UI access to users who belong to one or more of the listed organizations. Configure this field if your OAuth provider allows you to separate users into organizations. If your OAuth provider does not allow you to separate users into organizations, do not configure this field.
For Allowed groups, enter a comma-separated list of groups. Configuring this field limits Grafana UI access to users who belong to one or more of the listed groups. Configure this field if your OAuth provider allows you to separate users into groups. If your OAuth provider does not allow you to separate users into groups, do not configure this field.
(Optional) For Role attribute path, enter a JMESPath string that maps users to Grafana roles. For example, contains(scope[*], 'healthwatch.admin') && 'Admin' || contains(scope[*], 'healthwatch.edit') && 'Editor' || contains(scope[*], 'healthwatch.read') && 'Viewer'.
(Optional) To prevent users who are not mapped to a valid Grafana role from accessing the Grafana UI, activate the Deny access to users without Grafana roles checkbox. This checkbox is deactivated by default. Deactivating this checkbox assigns the Viewer role to users who cannot be not mapped to a valid Grafana role by the string configured in the Role attribute path field.
(Optional) To allow the Grafana instance to communicate with the server for your OAuth provider over TLS:
1. For Certificate and private key for TLS, provide a certificate and private key for the Grafana instance to use for TLS connections to the server for your OAuth provider.
2. For CA certificate for TLS, provide a certificate for the certificate authority (CA) that the server for your OAuth provider uses to verify TLS certificates.
3. If you do not provide a self-signed CA certificate or a certificate that is signed by a self-signed CA certificate, activate the Skip TLS certificate verification checkbox. When this checkbox is activated, the Grafana instance does not verify the identity of the server for your OAuth provider. This checkbox is deactivated by default.
Click Save.

Configure UAA Authentication

When you configure UAA authentication for the Grafana UI, users can log in to the Grafana UI with their UAA credentials.

Healthwatch can automatically configure authentication with the UAA instance of the runtime that is installed on the same Ops Manager foundation as the Healthwatch tile, either VMware Tanzu Application Service for VMs (TAS for VMs) or Tanzu Kubernetes Grid Integrated Edition (TKGI). If you want to configure authentication with the UAA instance of TAS for VMs or TKGI installed on the same Ops Manager foundation, follow the procedure below. If you want to configure authentication with the UAA instance of a runtime that is installed on a different Ops Manager foundation, you must manually configure it using the fields described in Configure Generic OAuth Authentication above.

To configure UAA authentication for the Grafana UI:

Under Additional authentication methods, select UAA.
Note: If you are configuring authentication with the UAA instance for a TKGI deployment, Healthwatch does not add the UAA administrator user account to the healthwatch.admin group by default. If you want to log in to the Grafana UI using the UAA administrator credentials, you must manually add the UAA administrator user account to the healthwatch.admin group.
To assign Admin, Editor, or Viewer Grafana roles to a user:
1. Target the UAA server by running:
```
uaac target UAA-URL
```
  Where UAA-URL is the URL of the UAA instance with which you want to configure authentication. For UAA instances for TAS for VMs, this URL is usually https://login.SYSTEM-DOMAIN, where SYSTEM-DOMAIN is the domain you configured in the System domain field in the Domains pane of the TAS for VMs tile. For TKGI, this URL is usually https://TKGI-API-URL:8443, where TKGI-API-URL is the URL of the TKGI API.
2. Assign Admin, Editor, or Viewer Grafana roles to a user by running:
```
uaac member add GROUP USERNAME
```
  Where:
  - GROUP is either healthwatch.admin, healthwatch.edit, or healthwatch.read. These groups map to the Admin, Editor, and Viewer Grafana roles, respectively. For more information about the level of access each role provides, see the Grafana documentation.
  - USERNAME is the username of the user to which you want to assign a Grafana role.
Click Save.

Configure LDAP Authentication

When you configure LDAP authentication for the Grafana UI, users can log in to the Grafana UI with their LDAP credentials. You can also create mappings between LDAP group memberships and Grafana org user roles. For more information about configuring LDAP authentication, see the Grafana documentation.

To configure LDAP authentication for the Grafana UI:

Navigate to the Ops Manager Installation Dashboard.
Click the Healthwatch tile.
Select Grafana Authentication.
Under Additional authentication methods, select LDAP.
For Host address, enter the network address of your LDAP server host.
(Optional) For Port, enter the port for your LDAP server host. The default port is 389 when the Use TLS checkbox is activated, or 636 when the Use TLS checkbox is deactivated.
(Optional) To allow new users to create a new Grafana account when they log in with their existing LDAP credentials for the first time, activate the Allow new accounts with existing LDAP credentials checkbox. This checkbox is activated by default. Deactivating this checkbox prevents users without a pre-existing Grafana account from creating a new Grafana account or logging in to the Grafana UI with their existing LDAP credentials.
(Optional) To allow the LDAP server to communicate with the Grafana instance over TLS when authenticating user credentials, activate the Use TLS checkbox. This checkbox is deactivated by default.
(Optional) To allow the LDAP server to run the STARTTLS command when communicating with the Grafana instance over TLS, activate the Use STARTTLS checkbox. This checkbox is deactivated by default.
(Optional) To allow the Grafana instance to skip TLS certificate verification when communicating with the LDAP server over TLS, activate the Skip TLS certificate verification checkbox. This checkbox is deactivated by default.
(Optional) For Bind DN, enter the distinguished name (DN) for binding to the LDAP server. For example, cn=admin,dc=grafana,dc=org.
(Optional) For Bind password, enter the password for binding to the LDAP server. For example, grafana.
(Optional) For User search filter, enter a regex string that defines LDAP user search criteria. For example, (cn=%s).
(Optional) For Search base DNs, enter an array of base DNs in the LDAP directory tree from which any LDAP user search begins. The typical LDAP search base matches your domain name. For example, dc=grafana,dc=org.
(Optional) For Group search filter, enter a regex string that defines LDAP group search criteria. For example, (&(objectClass=posixGroup)(memberUid=%s)).
(Optional) For Group search base DNs, enter an array of base DNs in the LDAP directory tree from which any LDAP group search begins. For example, ou=groups,dc=grafana,dc=org.
(Optional) For Group search filter user attribute, enter a value that defines which user attribute is substituted for %s in the regex string you entered for Group search filter. You can use the value of any property listed in Server attributes below. The default value is the value of the username property.
(Optional) For Server attributes, enter in TOML format tables of the LDAP attributes that your LDAP server uses. Each table must use the table name [servers.attributes].
(Optional) For Server group mappings, enter in TOML format an array of tables of LDAP groups mapped to Grafana orgs and roles. Each table must use the table name [[servers.group_mappings]]. For more information, see the Grafana documentation.
(Optional) To allow the Grafana instance to communicate with your LDAP server over TLS:
1. For Certificate and private key for TLS, provide a certificate and private key for the Grafana instance to use for TLS connections to your LDAP server.
2. For CA certificate for TLS, provide a certificate for the CA that your LDAP server uses to verify TLS certificates.
Click Save.

Configure Only Basic Authentication

If you want to only allow users with Grafana administrator credentials to log in to the Grafana UI, you can configure the Grafana UI to use only basic authentication.

To configure only basic authentication for the Grafana UI:

Navigate to the Ops Manager Installation Dashboard.
Click the Healthwatch tile.
Select Grafana Authentication.
Under Basic authentication, select Allow.
Under Additional authentication methods, select None.
Click Save.