5.5 Securing a Commercial Off-The-Shelf (COTS) application

Securing Grafana/GitLab with ZTrust using OAuth

ZTrust integrates with COTS applications using OpenID Connect (OIDC) to handle authentication and authorization. This setup enables secure login and role-based access for your applications.

Prerequisites

Before integrating your Spring Boot application with ZTrust, ensure the following are in place:

• ZTrust SSO – A running ZTrust instance that will act as the identity and access management provider.

• Configured Realm and Client – A realm and client must already be created in ZTrust, with the client configured for OIDC. These settings will be used by your COTS applications to authenticate users and validate tokens.

• Admin Access to COTS applications - Administrator access to the COTS applications is required as there are configurations needed to be done for OAuth 2.0 integration.

With these prerequisites, your application will be ready to establish a secure connection with ZTrust using OpenID Connect.

ZTrust Endpoints (OIDC)

These will be used in application configs:

Issuer URL:     https://<Ztrust-host>/realms/<realm-name>
Auth URL:       https://<Ztrust-host>/realms/<realm-name>/protocol/openid-connect/auth
Token URL:      https://<Ztrust-host>/realms/<realm-name>/protocol/openid-connect/token
User Info URL:  https://<Ztrust-host>/realms/<realm-name>/protocol/openid-connect/userinfo
JWKS URL:       https://<Ztrust-host>/realms/<realm-name>/protocol/openid-connect/certs

Set up ZTrust

Here, we are setting up ZTrust for Grafana. Other COTS applications like GitHub, GitLab can be setup in a similar way.

1. Log in to ZTrust Admin Console

   

   Fig 5.5.a: Master realm welcome page

2. Click on Manage Realms in the sidebar to view the list of realms available in your ZTrust.

   

   Fig 5.5.b: List of avalible realms under manage realms

3. From the list of realms, select the realm where you want to configure COTS applications.

   

   Fig 5.5.c: Welcome to Demo realm

4. From the left sidebar, navigate to the Clients section.

   

   Fig 5.5.d: Navigating to clients section in side bar

5. You will see a list of clients (applications). Choose/ Create the client for which you want to secure COTS Application.

   

   Fig 5.5.e: List of available clients

6. After selecting your client, you will taken to its settings page. Let's check out grafana-client that will be used to integrate Grafana with ZTrust.

   

   Fig 5.5.f: Client settings page

7. Enter your application’s redirect URL in the Valid Redirect URIs field.

   

   Fig 5.5.g: In client setting tab general settings fields

8. Then under Capability config turn on Client authentication and save.

   

   Fig 5.5.h: In client setting tab capability config options

9. You will now see a new tab enabled, called Credentials.

   

   Fig 5.5.i: Client settings tab

10. Navigate to the Credentials tab, where you can view and copy the Client Secret.

    

    Fig 5.5.j: Navigating to Credentials tab

11. With the ZTrust configuration complete, we can now move on to the Grafana side of the setup.

Grafana Setup

Edit the Grafana config file (e.g., /etc/grafana/grafana.ini):

[auth.generic_oauth]
enabled = true
name = Ztrust
allow_sign_up = true
client_id = grafana
client_secret = <your-client-secret>
scopes = openid profile email
auth_url = https://<Ztrust-host>/realms/<realm-name>/protocol/openid-connect/auth
token_url = https://<Ztrust-host>/realms/<realm-name>/protocol/openid-connect/token
api_url = https://<Ztrust-host>/realms/<realm-name>/protocol/openid-connect/userinfo

;set to true if Ztrust returns groups/roles;
allow_assign_grafana_admin = true

Then restart Grafana:

sudo systemctl restart grafana-server

GitLab setup

Step 1: Register GitLab as Client in ZTrust

Setup ZTrust in a similar way to Grafana with the below details:

• Client ID: gitlab-client

• Redirect URI: https://gitlab.example.com/users/auth/openid_connect/callback

Adjust domain as per your GitLab instance.

Step 2: Configure GitLab

Edit GitLab config (/etc/gitlab/gitlab.rb):

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Ztrust",
    args: {
      name: "openid_connect",
      scope: ["openid", "profile", "email"],
      response_type: "code",
      issuer: "https://<Ztrust-host>/realms/<realm-name>",
      discovery: true,
      client_auth_method: "query",
      uid_field: "preferred_username",
      client_options: {
        identifier: "gitlab",
        secret: "<your-client-secret>",
        redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
      }
    }
  }
]

Then reconfigure GitLab:

sudo gitlab-ctl reconfigure