Configuring Authentication with a UAA Instance on a Different Ops Manager Foundation

This topic describes how to configure authentication with a User Account and Authentication (UAA) instance on a different VMware Tanzu^® Operations Manager™ (Ops Manager) foundation for users to log in to the Grafana UI.

Overview of UAA Authentication with the Grafana UI

Healthwatch™ for VMware Tanzu^® (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™ (TAS for VMs) or VMware Tanzu^® Kubernetes Grid™ Integrated Edition (TKGI). When you select UAA as your Grafana UI authentication method in the Grafana Authentication pane of the Healthwatch tile, Healthwatch automatically configures authentication with the UAA instances in TAS for VMs and TKGI for the Grafana UI.

If you want to configure authentication with the UAA instance of a runtime that is installed on a different Ops Manager foundation, you must select Generic OAuth and configure it manually through the Grafana Authentication pane.

Create a UAA Client for the Grafana Instance

To authenticate with the the UAA instance of a runtime that is installed on a different Ops Manager foundation, the Grafana instance must access the UAA instance through a UAA client.

To create a UAA client for the Grafana instance:

Navigate to the Ops Manager Installation Dashboard for the Ops Manager foundation with the UAA instance with which you want to configure authentication for the Grafana UI.
Click the VMware Tanzu Application Service or Tanzu Kubernetes Grid Integrated Edition tile, depending on which runtime is installed on this Ops Manager foundation.
Select the Credentials tab.
View and record the credentials to log in to the UAA instance for the runtime installed on this Ops Manager foundation:
- 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.
Target the server for the UAA instance for the runtime installed on this Ops Manager foundation using the User Account and Authentication Command Line Interface (UAAC). Run:
```
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.

For more information about the UAAC, see the TAS for VMs documentation.
Log in to the UAA instance by running:
```
uaac token client get admin -s UAA-ADMIN-CLIENT-SECRET
```
Where UAA-ADMIN-CLIENT-SECRET is the UAA administrator client secret you recorded from the Credentials tab in the runtime tile in a previous step.
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,refresh_token \
   --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.
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.
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.
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 Grafana UI

To configure the Grafana UI to authenticate users with a UAA instance on a different Ops Manager foundation:

Navigate to the Ops Manager Installation Dashboard for the Ops Manager foundation with the Grafana instance for which you want to configure UAA authentication.
Click the Healthwatch tile.
Select Grafana Authentication.
Under Additional authentication methods, select Generic OAuth.
For Provider name, enter a name that identifies the UAA instance with which you want to configure authentication. For example, UAA.
For Client ID, enter the client ID of the UAA client that was created for the UAA instance with which you want to configure authentication in Create a UAA Client for the Grafana Instance above.
For Client secret, enter the client secret of the UAA client that was created for the UAA instance with which you want to configure authentication in Create a UAA Client for the Grafana Instance above.
For Scopes, enter openid,healthwatch.admin,healthwatch.edit,healthwatch.read.
For Authorization URL, enter the authorization URL for your runtime:
- For TAS for VMs, enter https://login.sys.DOMAIN/oauth/authorize, where DOMAIN is the system domain of your Ops Manager deployment.
- For TKGI, enter https://api.pks.DOMAIN:8443/oauth/authorize, where DOMAIN is the system domain of your Ops Manager deployment.
For Token URL, enter the token URL for your runtime:
- For TAS for VMs, enter https://login.sys.DOMAIN/oauth/token, where DOMAIN is the system domain of your Ops Manager deployment.
- For TKGI, enter https://api.pks.DOMAIN:8443/oauth/token, where DOMAIN is the system domain of your Ops Manager deployment.
For API URL, enter http://localhost:3002/userinfo. This is the URL of a local proxy server that Healthwatch can use to translate the UAA token into a format that is compatible with Grafana.
To allow new users to create a new Grafana account when they log in with their existing UAA 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 UAA credentials.
For Role attribute path, enter the following JMESPath string to map users to Grafana roles: 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 CA certificate for TLS, provide a certificate for the certificate authority (CA) that the UAA instance with which you want to configure authentication uses to verify TLS certificates. You must configure this field if the UAA instance with which you want to configure authentication uses a TLS certificate that is signed by an untrusted authority.
2. 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 UAA instance with which you want to configure authentication. This checkbox is deactivated by default. VMware does not recommend skipping TLS certificate verification to a UAA instance for a runtime on a different Ops Manager foundation.
Click Save.