Configuring Grafana Authentication

Page last updated:

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

However, you can configure the Grafana UI to use a different authentication method instead. This enables 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 User Authentication Overview in the Grafana documentation.

The values that you enter in the fields in the Grafana Configuration pane define their corresponding properties in the Grafana configuration file. For more information, see Configuration in 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 Configuration.

  4. Under Select an authentication mechanism for Grafana, select Basic.

  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 Generic OAuth Authentication in 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 Configuration.

  4. Under Select an authentication mechanism for Grafana, select Generic OAuth.

  5. For Name, enter the name of the OAuth provider you want to configure. This name appears as the name property in the [auth.generic_oauth] section of the Grafana configuration file.

  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 User Authentication Overview in the Grafana documentation. This client ID appears as the client_id property in the [auth.generic_oauth] section of the Grafana configuration file.

  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 User Authentication Overview in the Grafana documentation. This client secret appears as the client_secret property in the [auth.generic_oauth] section of the Grafana configuration file.

  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 User Authentication Overview in the Grafana documentation. This list appears as the scopes property in the [auth.generic_oauth] section of the Grafana configuration file.

  9. For Authorization URL, enter the authorization URL of your OAuth provider server. This URL appears as the auth_url property in the [auth.generic_oauth] section of the Grafana configuration file.

  10. For Token URL, enter the token URL of your OAuth provider server. This URL appears as the token_url property in the [auth.generic_oauth] section of the Grafana configuration file.

  11. For Api URL, enter the API URL of your OAuth provider server. This URL appears as the api_url property in the [auth.generic_oauth] section of the Grafana configuration file.

  12. (Optional) For Email Attribute Name, enter the attribute name that contains the email address of the user. For more information, see Generic OAuth Authentication in the Grafana documentation. This name appears as the email_attribute_name property in the [auth.generic_oauth] section of the Grafana configuration file.

  13. (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. This list appears as the allowed_domains property in the [auth.generic_oauth] section of the Grafana configuration file.

  14. (Optional) For Hosted Domain, enter the domain of your Grafana instance. This domain appears as the domain property in the [server] section of the Grafana configuration file. You must configure this field if your OAuth provider requires a callback URL that uses the root URL of your Grafana instance. If your OAuth provider does not require a callback URL, do not configure this field.

  15. (Optional) To allow new users to log in to the Grafana UI with their existing OAuth credentials, enable the Allow Sign Up checkbox. This checkbox is enabled by default. Disabling this checkbox prevents users without a pre-existing Grafana account from logging in to the Grafana UI with their existing OAuth credentials. This checkbox appears as the allow_sign_up property in the [auth.generic_oauth] section of the Grafana configuration file.

  16. (Optional) For Team IDs, 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. This list appears as the team_ids property in the [auth.generic_oauth] section of the Grafana configuration file.

  17. (Optional) 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. This list appears as the allowed_organizations property in the [auth.generic_oauth] section of the Grafana configuration file.

  18. (Optional) 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. This list appears as the allowed_groups property in the [auth.generic_oauth] section of the Grafana configuration file.

  19. (Optional) To configure TLS communication between the Grafana instance and your OAuth provider server:

    1. For TLS Credentials, provide at least one certificate and private key to enable TLS communication between the Grafana instance and your OAuth provider server. These certificates and private keys appear as the tls_client_cert and tls_client_key properties in the [auth.generic_oauth] section of the Grafana configuration file.
    2. For TLS CA, provide a certificate authority (CA) that signs the certificates you provide in the TLS Credentials field above. This CA appears as the tls_client_ca property in the [auth.generic_oauth] section of the Grafana configuration file.
    3. If you do not provide a self-signed CA or a certificate that is signed by a self-signed CA in the TLS CA field, enable the Skip TLS Verification checkbox to enable the Grafana VM skip SSL validation when connecting to your OAuth provider server. This checkbox is disabled by default. This checkbox appears as the tls_skip_verify_insecure property in the [auth.generic_oauth] section of the Grafana configuration file.
  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 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 foundation.

  3. Select the Credentials tab.

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

    • If your Ops Manager deployment uses internal authentication:
      1. View the credentials for the UAA admin client for your runtime:
        • For TAS for VMs: In the Admin Client Credentials row of the UAA section, click Link to Credential.
        • For TKGI: In the Pks Uaa Management Admin Client row, click Link to Credential.
      2. Record the secret for the UAA admin client:
        • For TAS for VMs: Record the value of password. This value is the secret for Admin Client Credentials.
        • For TKGI: Record the value of secret. This value is the secret for Pks Uaa Management Admin Client.
    • If your Ops Manager deployment uses SAML or LDAP authentication:
      1. View the credentials for the UAA admin client for your runtime:
        • For TAS for VMs: In the Admin Client Credentials row of the UAA section, click Link to Credential.
        • For TKGI: In the Pks Uaa Management Admin Client row, click Link to Credential.
      2. Record the secret for the UAA admin client:
        • For TAS for VMs: Record the value of password. This value is the secret for Admin Client Credentials.
        • For TKGI: Record the value of secret. This value is the secret for Pks Uaa Management Admin Client.
      3. Return to the Ops Manager Installation Dashboard.
      4. Click the BOSH Director tile.
      5. Select the Credentials tab.
      6. In the Uaa Bosh Client Credentials row of the BOSH Director section, click Link to Credential.
      7. Record the value of password. This value is the secret for Uaa Bosh Client Credentials.
  5. Target the server for your UAA instance for your runtime by running:

    uaac target uaa.UAA-DOMAIN
    

    Where UAA-DOMAIN is the domain of your UAA server.

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

    • If your Ops Manager deployment uses internal authentication, run:

      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.

    • If your Ops Manager deployment uses SAML or LDAP authentication:

      1. Run:

        uaac token owner get login -s UAA-LOGIN-CLIENT-SECRET
        

        Where UAA-LOGIN-CLIENT-SECRET is the UAA login client secret you recorded from the Credentials tab in the BOSH Director tile in a previous step.

      2. When prompted, enter the UAA admin client username admin and 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 your Grafana instance to use in the Grafana Configuration pane of the Healthwatch tile.
    • GRAFANA-ROOT-URL is the root URL for your Grafana instance. If your Grafana instance uses HTTPS, include the port for your Grafana instance in GRAFANA-ROOT-URL. For example, https://GRAFANA-ROOT-URL:443. Your Grafana instance listens on either port 443 or 80, depending on whether you provide an SSL certificate in the Enable HTTPS by providing certificates field in the Grafana Configuration pane of the Healthwatch tile.
  8. Create a user account for the UAA client you created in the 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.
  9. Add the user account you created in the previous step to the healthwatch.read group by running:

    uaac member add healthwatch.read USERNAME
    

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

  4. Under Select an authentication mechanism for Grafana, 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 URL for UAA, enter login.SYSTEM-DOMAIN, where SYSTEM-DOMAIN is the system domain for your runtime.

  8. (Optional) To enable TLS communication between the Grafana instance and your UAA server, configure one of the following options:

    • To configure the Grafana instance to use a self-signed CA or a certificate that is signed by a self-signed CA when communicating with your UAA server over TLS, provide the CA in TLS CA.
    • If you do not provide a self-signed CA or a certificate that is signed by a self-signed CA in the TLS CA field, enable the Skip TLS Verification checkbox to enable the Grafana instance to skip SSL validation when connecting to the UAA server. This checkbox is disabled 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 LDAP Authentication in 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 Configuration.

  4. Under Select an authentication mechanism for Grafana, select LDAP.

  5. For Host, enter the network address of your LDAP server host. This network address appears as the host property in the [auth.ldap] section of the Grafana configuration file.

  6. (Optional) For Port, enter the port for your LDAP server host. The default port is 389 when the Use SSL checkbox is disabled, or 636 when the Use SSL checkbox is enabled. This port appears as the port property in the [auth.ldap] section of the Grafana configuration file.

  7. (Optional) To allow new users to log in to the Grafana UI with their existing LDAP credentials, enable the Allow sign up checkbox. This checkbox is enabled by default. Disabling this checkbox prevents users without a pre-existing Grafana account from logging in to the Grafana UI with their existing LDAP credentials. This checkbox appears as the allow_sign_up property in the [auth.ldap] section of the Grafana configuration file.

  8. (Optional) To enable the LDAP server to communicate with the Grafana instance over TLS when authenticating user credentials, enable the Use SSL checkbox. This checkbox is disabled by default. This checkbox appears as the use_ssl property in the [auth.ldap] section of the Grafana configuration file.

  9. (Optional) To enable the LDAP server to run the STARTTLS command when communicating with the Grafana instance over TLS, enable the Start TLS checkbox. This checkbox is disabled by default. This checkbox appears as the start_tls property in the [auth.ldap] section of the Grafana configuration file.

  10. (Optional) To enable the Grafana instance to skip SSL validation when communicating with the LDAP server over TLS, enable the Skip SSL Verification checkbox. This checkbox is disabled by default. This checkbox appears as the ssl_skip_verify property in the [auth.ldap] section of the Grafana configuration file.

  11. (Optional) For Bind DN, enter the distinguished name (DN) for binding to the LDAP server. For example, "cn=admin,dc=grafana,dc=org". This DN appears as the bind_dn property in the [auth.ldap] section of the Grafana configuration file.

  12. (Optional) For Bind password, enter the password for binding to the LDAP server. For example, grafana. This password appears as the bind_password property in the [auth.ldap] section of the Grafana configuration file.

  13. (Optional) For User search filter, enter a regex string that defines LDAP user search criteria. For example, "(cn=%s)". This string appears as the search_filter property in the [auth.ldap] section of the Grafana configuration file.

  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". This array appears as the search_base_dns property in the [auth.ldap] section of the Grafana configuration file.

  15. (Optional) For Group search filter, enter a regex string that defines LDAP group search criteria. For example, "(&(objectClass=posixGroup)(memberUid=%s))". This string appears as the group_search_filter property in the [auth.ldap] section of the Grafana configuration file.

  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". This array appears as the group_search_base_dns property in the [auth.ldap] section of the Grafana configuration file.

  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 under [server.attributes] in the [auth.ldap] section of the Grafana configuration file. The default value is the value of the username property. This value appears as the group_search_filter_user_attribute property in the [auth.ldap] section of the Grafana configuration file.

  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]. These tables appear under [servers.attributes] in the [auth.ldap] section of the Grafana configuration file.

  19. (Optional) For Server group mappings, enter in TOML format an array of tables of LDAP groups mapped to a Grafana org and role. Each table must use the table name [[servers.group_mappings]]. This array of tables appears under a [[servers.group_mappings]] heading in the [auth.ldap] section of the Grafana configuration file. For more information, see Group Mappings in LDAP Authentication in the Grafana documentation.

  20. (Optional) To configure TLS communication between the Grafana instance and your LDAP server:

    1. For TLS Credentials, provide at least one certificate and private key to enable TLS communication between the Grafana instance and your LDAP server. These certificates and private keys appear as the client_cert and client_key properties in the [auth.ldap] section of the Grafana configuration file.
    2. For TLS CA, provide a CA that signs the certificates you provide in the TLS Credentials field above. This CA appears as the root_ca_cert property in the [auth.ldap] section of the Grafana configuration file.
  21. Click Save.