From 30cfb9fdaed9561283256af313476a1f9a0fcbd4 Mon Sep 17 00:00:00 2001 From: Tung Manh Hoang Date: Mon, 22 Jun 2026 11:03:00 +0700 Subject: [PATCH 1/2] docs(debugging): add Linux + broaden self-signed SSL cert trust scope (KOB-51426) Migrate the end-user portion of the Confluence "Deploy SSL cert to end-user machines" section into the public docs. - Add a Linux tab (Debian-based and Arch/Fedora trust steps). - Add a note to restart Chrome, Kobiton CLI, virtualUSB, or any AI coding assistant connected through the Kobiton MCP server after import. - Broaden the page intro and section note from virtualUSB-only to Portal Web, virtualUSB, Kobiton CLI, and Kobiton MCP server. - Align the macOS step to trust the root CA certificate, matching the Windows/Linux tabs and the source. --- .../configure-your-personal-computer.adoc | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc b/docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc index 632030557..7f8550a51 100644 --- a/docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc +++ b/docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc @@ -2,7 +2,7 @@ :navtitle: Configure personal computer for Standalone Portal :tabs-sync-option: -Learn how to configure your personal computer for Standalone Portal with SSL, so you can debug local or private devices using virtualUSB. +Configure your personal computer to trust a Standalone/On-Prem Portal that uses a self-signed SSL certificate. Trusting the certificate is required to access the Portal Web and to use virtualUSB, Kobiton CLI, and any AI coding assistant connected through the Kobiton MCP server. [#_before_you_start] == Before you start @@ -14,7 +14,7 @@ You'll need to complete the following: == Trust self-signed SSL certificate (Standalone/On-Prem only) [NOTE] -These steps are only necessary if the Standalone/On-Prem portal uses a self-signed SSL certificate. +These steps are only necessary if the Standalone/On-Prem Portal uses a self-signed SSL certificate. Import the certificate on each end-user computer that accesses the Portal Web, runs virtualUSB, runs Kobiton CLI commands, or connects through the Kobiton MCP server. [tabs] ==== @@ -23,11 +23,11 @@ macOS:: + -- -Request the IT administrator of your organization for the SSL end-entity certificate. It should be a file named `ssl.crt`. Transfer the certificate file to the computer. +Request the IT administrator of your organization for the root CA certificate that issued the SSL end-entity certificate. It is typically named `root.crt` or `ca.crt`. Transfer the certificate file to the computer. Open the *Keychain Access* application. -Open *Finder*, go to the location of the `ssl.crt` file, then drag and drop the file into the *Keychain Access* application. +Open *Finder*, go to the location of the root CA certificate file, then drag and drop the file into the *Keychain Access* application. Double-click on the newly added certificate file. In the dialog, choose the Always Trust option from the dropdown list for the two fields: @@ -45,7 +45,7 @@ Windows:: + -- -Request the IT administrator of your organization for the root CA certificate that issued the SSL end-entity certificate. It should be a file named `root.crt` or `ca.crt`. Transfer the certificate file to the computer. +Request the IT administrator of your organization for the root CA certificate that issued the SSL end-entity certificate. It is typically named `root.crt` or `ca.crt`. Transfer the certificate file to the computer. On the Windows machine, double-click the file, then select *Install Certificate* on the *Certificate* window. @@ -67,4 +67,19 @@ Select *Next*, then *Finish*. The root CA certificate is now imported to the end -- +Linux:: ++ +-- + +Request the IT administrator of your organization for the root CA certificate that issued the SSL end-entity certificate. It is typically named `root.crt` or `ca.crt`. Transfer the certificate file to the computer, then trust it using the steps for your distribution: + +* Debian-based: copy the certificate to `/usr/local/share/ca-certificates` (create the directory if it does not exist), then run `update-ca-certificates` as root. + +* Arch or Fedora: copy the certificate to `/etc/ca-certificates/trust-source/anchors`, then run `update-ca-trust` as root. + +-- + ==== + +[NOTE] +After importing the certificate, restart the Chrome browser, Kobiton CLI, the virtualUSB application, or any AI coding assistant connected through the Kobiton MCP server before connecting to the Portal. From 15995ffd1d5b15674ec4aabe474aba67704964c4 Mon Sep 17 00:00:00 2001 From: Tung Manh Hoang Date: Mon, 22 Jun 2026 16:40:58 +0700 Subject: [PATCH 2/2] update the guide to trust self-signed ssl cert for virtualUSB and re-use it for MCP server --- docs/modules/ai/pages/mcp/claude-code.adoc | 11 ++- .../ai/pages/mcp/install-local-ai-plugin.adoc | 10 ++- .../configure-your-personal-computer.adoc | 73 +------------------ .../partials/trust-self-signed-ssl-cert.adoc | 65 +++++++++++++++++ 4 files changed, 88 insertions(+), 71 deletions(-) create mode 100644 docs/modules/debugging/partials/trust-self-signed-ssl-cert.adoc diff --git a/docs/modules/ai/pages/mcp/claude-code.adoc b/docs/modules/ai/pages/mcp/claude-code.adoc index 0a6fb561e..5eccd485d 100644 --- a/docs/modules/ai/pages/mcp/claude-code.adoc +++ b/docs/modules/ai/pages/mcp/claude-code.adoc @@ -121,7 +121,16 @@ Once you have obtained the custom URL, create a `.mcp.json` file in your project Replace `\https://api-custom-domain.kobiton.com/mcp` with the actual URL of your Kobiton MCP server. -After creating the file, continue with either OAuth or API key authentication. +After creating the file, continue with either <> or <> . For Standalone customer with self-signed SSL certificate, trust the certificate before authenticating. + +== Trust self-signed SSL certificate (Standalone/On-Prem only) + +These steps are only necessary if the Standalone/On-Prem Portal uses a self-signed SSL certificate. Import the certificate on each end-user computer that runs Claude Code. + +include::debugging:partial$trust-self-signed-ssl-cert.adoc[] + +After importing the certificate, restart Claude Code before authenticating with the MCP server. + [[oauth-authentication]] === OAuth authentication (recommended) diff --git a/docs/modules/ai/pages/mcp/install-local-ai-plugin.adoc b/docs/modules/ai/pages/mcp/install-local-ai-plugin.adoc index 1d4529a98..0003b94cc 100644 --- a/docs/modules/ai/pages/mcp/install-local-ai-plugin.adoc +++ b/docs/modules/ai/pages/mcp/install-local-ai-plugin.adoc @@ -136,7 +136,7 @@ For all files above, replace the default value of `url` with the custom MCP serv == Install local plugin -Run the commands in the table below in a command-line tool on your machine according to the AI platform. Replace `/path/to/automate` with the actual path to the `automate` or `automate-main` folder. +Run the commands in the table below in a command-line tool on your machine according to the AI Agent tool. Replace `/path/to/automate` with the actual path to the `automate` or `automate-main` folder. [cols="1,2",options="header"] |=== @@ -189,6 +189,14 @@ Verify the URL of `kobiton` |=== +== Trust self-signed SSL certificate (Standalone/On-Prem only) + +These steps are only necessary if the Standalone/On-Prem Portal uses a self-signed SSL certificate. Import the certificate on each end-user computer that runs the AI Agent tool. + +include::debugging:partial$trust-self-signed-ssl-cert.adoc[] + +After importing the certificate, restart the AI Agent tool before authenticating with the MCP server. + == Authenticate and use the plugin Refer to the respective AI assistance tool guide to authenticate and use the plugin. diff --git a/docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc b/docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc index 7f8550a51..f513fa383 100644 --- a/docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc +++ b/docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc @@ -2,7 +2,7 @@ :navtitle: Configure personal computer for Standalone Portal :tabs-sync-option: -Configure your personal computer to trust a Standalone/On-Prem Portal that uses a self-signed SSL certificate. Trusting the certificate is required to access the Portal Web and to use virtualUSB, Kobiton CLI, and any AI coding assistant connected through the Kobiton MCP server. +Configure your personal computer to trust a Standalone/On-Prem Portal that uses a self-signed SSL certificate. Trusting the certificate is required to access the Portal Web and to use virtualUSB. [#_before_you_start] == Before you start @@ -13,73 +13,8 @@ You'll need to complete the following: == Trust self-signed SSL certificate (Standalone/On-Prem only) -[NOTE] -These steps are only necessary if the Standalone/On-Prem Portal uses a self-signed SSL certificate. Import the certificate on each end-user computer that accesses the Portal Web, runs virtualUSB, runs Kobiton CLI commands, or connects through the Kobiton MCP server. +These steps are only necessary if the Standalone/On-Prem Portal uses a self-signed SSL certificate. Import the certificate on each end-user computer that runs virtualUSB. -[tabs] -==== +include::partial$trust-self-signed-ssl-cert.adoc[] -macOS:: -+ --- - -Request the IT administrator of your organization for the root CA certificate that issued the SSL end-entity certificate. It is typically named `root.crt` or `ca.crt`. Transfer the certificate file to the computer. - -Open the *Keychain Access* application. - -Open *Finder*, go to the location of the root CA certificate file, then drag and drop the file into the *Keychain Access* application. - -Double-click on the newly added certificate file. In the dialog, choose the Always Trust option from the dropdown list for the two fields: - -* *Secure Sockets Layer (SSL)* - -* *X.509 Basic Policy* - -image:macos-ssl-cert-trust.png[width=800,alt="The trust option for the imported certificate in keychain access with the 2 options set as Always Trust"] - -Close the dialog and enter the admin password of the user workstation to save the changes. - --- - -Windows:: -+ --- - -Request the IT administrator of your organization for the root CA certificate that issued the SSL end-entity certificate. It is typically named `root.crt` or `ca.crt`. Transfer the certificate file to the computer. - -On the Windows machine, double-click the file, then select *Install Certificate* on the *Certificate* window. - -image:windows-certificate-install.png[width=400,alt="The certificate information screen with an option to Install Cerficicate"] - -On the next screen, choose *Local Machine*. This requires administrators privileges. - -image:windows-certificate-install-store.png[width=400,alt="The Certificate Import Wizard with the Store Location set to Local Machine"] - -On the next screen, choose *Place all certificates in the following store*, then select *Browse*. - -image:windows-certificate-browse-store.png[width=400,alt="The Certificate Store selector with the option Place all certificates in the following store selected"] - -Choose *Trusted Root Certification Authorities*, then select *OK*. - -image:windows-certificate-trusted-root.png[width=400,alt="The Select Certificate Store screen with Trusted Root Certification Authorities selected"] - -Select *Next*, then *Finish*. The root CA certificate is now imported to the end-user workstation trust store. - --- - -Linux:: -+ --- - -Request the IT administrator of your organization for the root CA certificate that issued the SSL end-entity certificate. It is typically named `root.crt` or `ca.crt`. Transfer the certificate file to the computer, then trust it using the steps for your distribution: - -* Debian-based: copy the certificate to `/usr/local/share/ca-certificates` (create the directory if it does not exist), then run `update-ca-certificates` as root. - -* Arch or Fedora: copy the certificate to `/etc/ca-certificates/trust-source/anchors`, then run `update-ca-trust` as root. - --- - -==== - -[NOTE] -After importing the certificate, restart the Chrome browser, Kobiton CLI, the virtualUSB application, or any AI coding assistant connected through the Kobiton MCP server before connecting to the Portal. +After importing the certificate, restart the virtualUSB application before authenticating with the Portal again. \ No newline at end of file diff --git a/docs/modules/debugging/partials/trust-self-signed-ssl-cert.adoc b/docs/modules/debugging/partials/trust-self-signed-ssl-cert.adoc new file mode 100644 index 000000000..ef18c0fee --- /dev/null +++ b/docs/modules/debugging/partials/trust-self-signed-ssl-cert.adoc @@ -0,0 +1,65 @@ +// Steps to trust self-signed ssl cert for Standalone Portal + +Request the IT administrator of your organization for the root CA certificate that issued the SSL end-entity certificate. It is typically named `root.crt` or `ca.crt`. Transfer the certificate file to the computer, then follow the appropriate steps for your operating system. + +.  +[tabs] +==== + +macOS:: ++ +-- + +Open the *Keychain Access* application. + +Open *Finder*, go to the location of the root CA certificate file, then drag and drop the file into the *Keychain Access* application. + +Double-click on the newly added certificate file. In the dialog, choose the Always Trust option from the dropdown list for the two fields: + +* *Secure Sockets Layer (SSL)* + +* *X.509 Basic Policy* + +image:debugging:macos-ssl-cert-trust.png[width=800,alt="The trust option for the imported certificate in keychain access with the 2 options set as Always Trust"] + +Close the dialog and enter the admin password of the user workstation to save the changes. + +-- + +Windows:: ++ +-- + +On the Windows machine, double-click the file, then select *Install Certificate* on the *Certificate* window. + +image:debugging:windows-certificate-install.png[width=400,alt="The certificate information screen with an option to Install Cerficicate"] + +On the next screen, choose *Local Machine*. This requires administrators privileges. + +image:debugging:windows-certificate-install-store.png[width=400,alt="The Certificate Import Wizard with the Store Location set to Local Machine"] + +On the next screen, choose *Place all certificates in the following store*, then select *Browse*. + +image:debugging:windows-certificate-browse-store.png[width=400,alt="The Certificate Store selector with the option Place all certificates in the following store selected"] + +Choose *Trusted Root Certification Authorities*, then select *OK*. + +image:debugging:windows-certificate-trusted-root.png[width=400,alt="The Select Certificate Store screen with Trusted Root Certification Authorities selected"] + +Select *Next*, then *Finish*. The root CA certificate is now imported to the end-user workstation trust store. + +-- + +Linux:: ++ +-- + +Trust the certificate using the steps for your distribution: + +* Debian-based: copy the certificate to `/usr/local/share/ca-certificates` (create the directory if it does not exist), then run `update-ca-certificates` as root. + +* Arch or Fedora: copy the certificate to `/etc/ca-certificates/trust-source/anchors`, then run `update-ca-trust` as root. + +-- + +====