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 ZTust for Grafana. Other COTS applications like GitHub, GitLab can be setup in a similar way.

1. Log in to ZTrust Admin Console

   

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

   

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

   

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

   

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

   

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.

   

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

   

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

   

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

   

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

    

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