# 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\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F3CFYuMdQrGvZPh4mvkcp%2Fimage.png?alt=media&#x26;token=9079e2dd-a3bb-4d08-9098-253df7399217" 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**.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FAeVUxDaUMgQmnQCTpMUr%2Fimage.png?alt=media&#x26;token=f7f3b7ea-5ec8-4e54-a154-7c63d41acf11" 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**.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FbXaN7CWO4K9CysxuHMZS%2Fimage.png?alt=media&#x26;token=fad61d41-6047-4f93-8f26-5a765d1f1fe6" alt=""><figcaption><p>Fig 5.5.c: Welcome to Demo realm</p></figcaption></figure>

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

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FzLIQGWWP8e1pOtG3ysBb%2Fimage.png?alt=media&#x26;token=55f3b23d-9037-4b21-81ae-fce5663d011c" 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.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2Fn9A3XV0yJXd0z64QGgOf%2Fimage.png?alt=media&#x26;token=1fae6cda-6ccd-4c89-8a8a-044abb44ccb5" 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.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FgumIkSRfpTTeJbKGef9i%2Fimage.png?alt=media&#x26;token=8a909380-d008-4cc0-afdb-8a18520ddfe8" 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.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FsaKFca9umI7oth9lsqvR%2Fimage.png?alt=media&#x26;token=34c7e4f1-5338-4d74-980f-a6210d9d8614" 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.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FtmgLB1TxpKk5cHyNVjJj%2Fimage.png?alt=media&#x26;token=73c4ece9-4b12-45a3-b2da-7de89e2d5919" 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**.\\

   <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2FL8CfYsZRX2Trpd1avMOX%2Fimage.png?alt=media&#x26;token=317e00d3-8efb-47b1-ab3f-bc99027a786c" 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**.\\

    <figure><img src="https://1778922777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3EUK5AUZv0UVaI5S0CTM%2Fuploads%2F7CA7LcbpZEipFAsKN1yv%2Fimage.png?alt=media&#x26;token=634bae5f-04eb-49b6-9545-d012ec750df9" 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
```
