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

Overview of Grafana Authentication

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 admin login credentials found in the Credentials tab of the Healthwatch for VMware Tanzu tile.

However, you can configure the Grafana UI to use a different authentication method instead. 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:

For a list of Grafana-supported authentication integrations, see the Grafana documentation.

The values that you configure in the Grafana 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, Configuring the Grafana Configuration File in Configuration File Reference Guide, and the Grafana documentation.

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

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

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the Healthwatch tile.

  3. Select Grafana.

  4. Under Grafana UI authentication method, select Basic authentication.

  5. Click Save.

  6. Select the Credentials tab.

  7. In the Admin Login Password row of the Grafana section, click Link to Credential.

  8. Record the value of password. This value is the password that all users must use to log in to the Grafana UI.

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. For more information about configuring generic OAuth authentication, see the Grafana documentation.

To configure generic OAuth authentication for the Grafana UI:

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the Healthwatch tile.

  3. Select Grafana.

  4. Under Grafana UI authentication method, select Generic OAuth.

  5. For Provider name, enter the name of your OAuth provider.

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

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

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

  9. For Authorization URL, enter the authorization URL of the server for your OAuth provider.

  10. For Token URL, enter the token URL of the server for your OAuth provider.

  11. For API URL, enter the API URL of the server for your OAuth provider.

  12. (Optional) For Email attribute, enter the attribute that contains the email address of the user. For more information, see the Grafana documentation.

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

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

  15. (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.

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

  17. For Allowed organizations, enter a comma-separated list of orgs. Configuring this field limits Grafana UI access to users who belong to one or more of the listed orgs. Configure this field if your OAuth provider allows you to separate users into orgs. If your OAuth provider does not allow you to separate users into orgs, do not configure this field.

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

  19. (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.

  20. Click Save.

Configure UAA Authentication

When you configure UAA authentication for the Grafana UI, users can log in to the Grafana UI with their credentials for 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).

To configure UAA authentication for the Grafana UI:

  1. Create a new UAA client for the Grafana instance. For more information, see Create a UAA Client for the Grafana Instance below.

  2. Configure the grafana UAA client in the Healthwatch tile. For more information, see Configure the UAA Client in Healthwatch below.

Create a UAA Client for the Grafana Instance

To facilitate UAA authentication, the Grafana instance must access the UAA instance for your runtime through a UAA client.

To create a UAA client for the Grafana instance:

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the VMware Tanzu Application Service or Tanzu Kubernetes Grid Integrated Edition tile, depending on which runtime is installed on your Ops Manager foundation.

  3. Select the Credentials tab.

  4. View and record the credentials to log in to the UAA instance for your runtime:

    • For TAS for VMs:
      1. In the Admin Client Credentials row of the UAA section, click Link to Credential.
      2. Record the value of password. This value is the secret for Admin Client Credentials.
    • For TKGI:
      1. In the Pks Uaa Management Admin Client row, click Link to Credential.
      2. Record the value of secret. This value is the secret for Pks Uaa Management Admin Client.

  5. Target the server for the UAA instance for your runtime using the User Account and Authentication Command Line Interface (UAAC). Run:

    uaac target UAA-URL

    Where UAA-URL is the URL of the UAA server for your runtime. 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.

    For more information about the UAAC, see the TAS for VMs documentation.

  6. Log in to the UAA instance for your runtime by running:

    ```
uaac token client get admin -s UAA-ADMIN-CLIENT-SECRET
```
Where `UAA-ADMIN-CLIENT-SECRET` is the UAA admin client secret you recorded from the **Credentials** tab in your runtime tile in a previous step.

  7. Create a UAA client for the Grafana instance by running:

    uaac client add grafana \
   --scope openid,healthwatch.admin,healthwatch.edit,healthwatch.read \
   --secret CLIENT-SECRET \
   --authorities uaa.resource \
   --authorized_grant_types authorization_code \
   --redirect_uri PROTOCOL://GRAFANA-ROOT-URL/login/generic_oauth

    Where: * CLIENT-SECRET is the secret you want to set for the UAA client. * PROTOCOL is either http or https, depending on the protocol you configured the Grafana instance to use in the Grafana pane of the Healthwatch tile. * GRAFANA-ROOT-URL is the root URL for the Grafana instance that you use to access the Grafana UI.

  8. If you are using TKGI, you must manually create UAA user groups to map to administrator, editor, and viewer permissions for Grafana. Run:

    uaac group add healthwatch.admin
uaac group add healthwatch.edit
uaac group add healthwatch.read

    If you are using TAS for VMs, you added the UAA client to UAA user groups mapped to administrator, editor, and viewer permissions for Grafana in the previous step. Continue to the next step.

  9. Create a user account for the UAA client you created in a previous step to log in to the Grafana instance. Run:

    uaac user add USERNAME -p SECRET --emails EMAIL

    Where: * USERNAME is the username you want to set for the user account. * SECRET is the secret you want to set for the user account. * EMAIL is the email address you want to associate with the user account.

  10. Assign user permissions to the user account you created in the previous step 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 you set for the user account you created in the previous step.

Configure the UAA Client in Healthwatch

After you create a UAA client for the Grafana instance, you must configure it in the Healthwatch tile.

To configure the UAA client for the Grafana instance in Healthwatch:

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the Healthwatch tile.

  3. Select Grafana.

  4. Under Grafana UI authentication method, select UAA.

  5. For Client ID, enter grafana.

  6. For Client secret, enter the secret you set for the grafana UAA client you created in Create a UAA Client for the Grafana Instance above.

  7. For UAA server root URL, enter login.SYSTEM-DOMAIN, where SYSTEM-DOMAIN is the system domain for your runtime.

  8. (Optional) To allow the Grafana instance to communicate with your UAA server over TLS, configure one of the following options:

    • To configure the Grafana instance to use a self-signed CA certificate or a certificate that is signed by a self-signed CA certificate when communicating with your UAA server over TLS, provide the CA certificate in CA certificate for TLS.
    • 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 your UAA server. This checkbox is deactivated by default.

  9. 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:

  1. Navigate to the Ops Manager Installation Dashboard.

  2. Click the Healthwatch tile.

  3. Select Grafana.

  4. Under Grafana UI authentication method, select LDAP.

  5. For Host address, enter the network address of your LDAP server host.

  6. (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.

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

  8. (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.

  9. (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.

  10. (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.

  11. (Optional) For Bind DN, enter the distinguished name (DN) for binding to the LDAP server. For example, cn=admin,dc=grafana,dc=org.

  12. (Optional) For Bind password, enter the password for binding to the LDAP server. For example, grafana.

  13. (Optional) For User search filter, enter a regex string that defines LDAP user search criteria. For example, (cn=%s).

  14. (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.

  15. (Optional) For Group search filter, enter a regex string that defines LDAP group search criteria. For example, (&(objectClass=posixGroup)(memberUid=%s)).

  16. (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.

  17. (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.

  18. (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].

  19. (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.

  20. (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.

  21. Click Save.

check-circle-line exclamation-circle-line close-line
Scroll to top icon