Skip to content

docs(debugging): trust self-signed SSL cert on end-user machines (KOB-51426) #497

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tungmhoang wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(debugging): trust self-signed SSL cert on end-user machines (KOB-51426) #497

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30cfb9f
docs(debugging): add Linux + broaden self-signed SSL cert trust scope…
tungmhoang Jun 22, 2026
15995ff
update the guide to trust self-signed ssl cert for virtualUSB and re-…
tungmhoang Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion docs/modules/ai/pages/mcp/claude-code.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<oauth-authentication,OAuth>> or <<api-key-authentication,API key authentication>> . For Standalone customer with self-signed SSL certificate, trust the certificate before authenticating.

@tiffany-kobiton tiffany-kobiton Jun 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The brackets are unnecessary. Restore to plain text "OAuth or API key authentication".


== Trust self-signed SSL certificate (Standalone/On-Prem only)

@tiffany-kobiton tiffany-kobiton Jun 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't use slash terms as per Microsoft style. "On-Prem" is an internal-sounding term. Users will know this type as "Standalone". You could say something like "Standalone (on premises deployment)" if you think clarification is needed, but only once near the beginning.


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)
Expand Down
10 changes: 9 additions & 1 deletion docs/modules/ai/pages/mcp/install-local-ai-plugin.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@tiffany-kobiton tiffany-kobiton Jun 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't use "machine" to refer to a computer as per Microsoft style.

I find this line confusing.


[cols="1,2",options="header"]
|===
Expand Down Expand Up @@ -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.
Expand Down
58 changes: 4 additions & 54 deletions docs/modules/debugging/pages/local-devices/configure-your-personal-computer.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@tiffany-kobiton tiffany-kobiton Jun 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this a "personal" computer? Shouldn't it be their org's computer?


[#_before_you_start]
== Before you start
Expand All @@ -13,58 +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.
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 SSL end-entity certificate. It should be a file named `ssl.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.

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 should be a file 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.

--

====
After importing the certificate, restart the virtualUSB application before authenticating with the Portal again.
65 changes: 65 additions & 0 deletions docs/modules/debugging/partials/trust-self-signed-ssl-cert.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

.&nbsp;
[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.

--

====
Loading