> For the complete documentation index, see [llms.txt](https://ztrust.gitbook.io/ztrust-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ztrust.gitbook.io/ztrust-documentation/user-manual-ztrust-v4.2/5.-securing-applications/5.5-securing-a-commercial-off-the-shelf-cots-application.md).

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

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

   <figure><img src="/files/De9Ji5EdPL5oiui6VEYU" alt=""><figcaption><p>Fig 5.5.a: Master realm welcome page</p></figcaption></figure>

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

   <figure><img src="/files/HDTBGt1691z2nPZAxymB" alt=""><figcaption><p>Fig 5.5.b: List of avalible realms under manage realms</p></figcaption></figure>

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

   <figure><img src="/files/SkZd1tHHm1y0nNSCPa7u" alt=""><figcaption><p>Fig 5.5.c: Welcome to Demo realm</p></figcaption></figure>

4. From the left **sidebar**, navigate to the **Clients** section.<br>

   <figure><img src="/files/FDbQy4gBO8hQROxTlEds" alt="" width="96"><figcaption><p>Fig 5.5.d: Navigating to clients section in side bar</p></figcaption></figure>

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

   <figure><img src="/files/SSFwP1JWqF76WvIbmwGg" alt=""><figcaption><p>Fig 5.5.e: List of available clients</p></figcaption></figure>

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

   <figure><img src="/files/EkV3xZgOokbPDPS1dEqB" alt=""><figcaption><p>Fig 5.5.f: Client settings page</p></figcaption></figure>

7. Enter your application’s **redirect URL** in the **Valid Redirect URIs** field.<br>

   <figure><img src="/files/OjCPYkmmQm31TQEOOwTG" alt=""><figcaption><p>Fig 5.5.g: In client setting tab general settings fields</p></figcaption></figure>

8. Then under **Capability** config turn on **Client authentication** and save.<br>

   <figure><img src="/files/MMLwFgCZDvwjJEAAj5ZV" alt="" width="563"><figcaption><p>Fig 5.5.h: In client setting tab capability config options</p></figcaption></figure>

9. You will now see a new tab enabled, called **Credentials**.<br>

   <figure><img src="/files/VqR2W88Sm7edWlMke4Q5" alt=""><figcaption><p>Fig 5.5.i: Client settings tab</p></figcaption></figure>

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

    <figure><img src="/files/ptCLSoe4tQS7XvgllAbZ" alt=""><figcaption><p>Fig 5.5.j: Navigating to Credentials tab</p></figcaption></figure>

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):

<pre class="language-ini"><code class="lang-ini">[auth.generic_oauth]
<strong>enabled = true
</strong>name = Ztrust
allow_sign_up = true
client_id = grafana
client_secret = &#x3C;your-client-secret>
scopes = openid profile email
auth_url = https://&#x3C;Ztrust-host>/realms/&#x3C;realm-name>/protocol/openid-connect/auth
token_url = https://&#x3C;Ztrust-host>/realms/&#x3C;realm-name>/protocol/openid-connect/token
api_url = https://&#x3C;Ztrust-host>/realms/&#x3C;realm-name>/protocol/openid-connect/userinfo

;set to true if Ztrust returns groups/roles;
allow_assign_grafana_admin = true
</code></pre>

Then restart Grafana:

```shell
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):

```ruby
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:

```shell
sudo gitlab-ctl reconfigure
```