Add instructions to securely manage token (Qiskit#2322)

Closes Qiskit#2255 --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Co-authored-by: Frank Harkins <frankharkins@hotmail.co.uk> Co-authored-by: Jessie Yu <jessieyu@us.ibm.com>
arnaucasau · Nov 27, 2024 · 74346aa · 74346aa
1 parent 6195846
commit 74346aa
Show file tree

Hide file tree

Showing 13 changed files with 252 additions and 125 deletions.
diff --git a/docs/guides/algorithmiq-tem.ipynb b/docs/guides/algorithmiq-tem.ipynb
@@ -123,7 +123,10 @@
     "\n",
     "tem_function_name = \"algorithmiq/tem\"\n",
     "\n",
-    "catalog = QiskitFunctionsCatalog(token=\"<YOUR_IQP_API_TOKEN>\")\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/functions\n",
+    "# to authenticate with your API token.\n",
+    "catalog = QiskitFunctionsCatalog()\n",
     "\n",
     "# Load your function\n",
     "tem = catalog.load(tem_function_name)"

diff --git a/docs/guides/functions.ipynb b/docs/guides/functions.ipynb
@@ -49,52 +49,97 @@
     "\n",
     "### Install Qiskit Functions Catalog client\n",
     "\n",
-    "To start using Qiskit Functions, install the IBM Qiskit Functions Catalog client:\n",
+    "1. To start using Qiskit Functions, install the IBM Qiskit Functions Catalog client:\n",
     "\n",
-    "`pip install qiskit-ibm-catalog`\n",
+    "    ```\n",
+    "    pip install qiskit-ibm-catalog\n",
+    "    ```\n",
+    "1. Retrieve your API token from the [IBM Quantum account page](https://quantum.ibm.com/account), and activate your Python virtual environment.  See the [installation instructions](/guides/install-qiskit#local) if you do not already have a virtual environment set up.\n",
     "\n",
-    "Once installed, authenticate using your [IBM Quantum Platform API token](http://quantum.ibm.com/) as follows:"
+    "    <span id=\"save-account\"></span>**If you are working in a trusted Python environment (such as on a personal laptop or workstation),** use the `save_account()` method to save your credentials locally. ([Skip to the next step](#functions-untrusted) if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)\n",
+    "\n",
+    "    To use `save_account()`, run `python` in your shell to open a REPL (read-eval-print loop), then enter the following:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
-   "id": "be135691-adee-4a1c-98bf-e76deb12319f",
+   "execution_count": null,
+   "id": "24dc565f-bb5d-4164-ba44-fc04c2fcaafd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "token = \"<your-token>\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "32919d16-4b5e-439a-8cda-33687a3d96b4",
    "metadata": {},
    "outputs": [],
    "source": [
     "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
     "\n",
-    "catalog = QiskitFunctionsCatalog(token=\"<YOUR_IQP_API_TOKEN>\")"
+    "QiskitFunctionsCatalog.save_account(token=token)"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "42843fcd-1779-4a74-8d6a-7d00c22e374e",
+   "id": "e458aad5-fa7c-4ba1-8e9e-be770d89a04a",
    "metadata": {},
    "source": [
-    "Optionally, you can use the `save_account()` method to save your credentials for easy access later on, before initializing the service. This saves your credentials in the same place as `QiskitRuntimeService.save_account()`, so you can skip this step if you had previously used `QiskitRuntimeService` to save your account. *Note that account credentials are saved in plain text, so only do so if you are using a trusted device.*"
+    "Close out of the REPL with `exit()`. From now on, whenever you need to authenticate to the service, you can load your credentials with `QiskitFunctionsCatalog()`."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "54fc48c8-3a65-478c-9bc3-ec6eb4db425a",
+   "id": "e872c222-aee9-40eb-8778-9a8e5434a11c",
    "metadata": {},
    "outputs": [],
    "source": [
-    "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
+    "# Load saved credentials\n",
+    "catalog = QiskitFunctionsCatalog()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "80441467-1d9a-4107-8570-22afa6e369f7",
+   "metadata": {},
+   "source": [
+    "3. <span id=\"functions-untrusted\"></span>**Avoid executing code on an untrusted machine or an external cloud Python environment to minimize security risks.** If you must use an untrusted environment (on, for example, a public computer), change your API token after each use by expiring it on the [IBM Quantum Platform dashboard](https://quantum.ibm.com/) (click the refresh button in the API token field) to reduce risk. To initialize the service in this situation, expand the following section to view code you can use:\n",
+    "\n",
+    "    <details>\n",
+    "        <summary>Initialize the service in an untrusted environment</summary>\n",
+    "\n",
+    "    ```python\n",
+    "    from qiskit-ibm-catalog import QiskitFunctionsCatalog\n",
+    "\n",
+    "    # After using the following code, go to your dashboard (https://quantum.ibm.com/)\n",
+    "    # and expire your API token (click the refresh button in the API token field)\n",
+    "    catalog = QiskitFunctionsCatalog(token=\"<MY_IBM_QUANTUM_TOKEN>\")\n",
+    "    ```\n",
+    "    </details>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6f2d0a37-1c6d-4cad-a9ce-c4d05c7aaaf1",
+   "metadata": {},
+   "source": [
+    "    <Admonition type=\"caution\">\n",
+    "      **Protect your API token!** Never include your token in source code, Python script, or notebook file. When sharing code with others, ensure that your API token is not embedded directly within the Python script. Instead, share the script without the token and provide instructions for securely setting it up.\n",
     "\n",
-    "# This can be skipped if you previously did QiskitRuntimeService.save_account()\n",
-    "QiskitFunctionsCatalog.save_account(token=\"<YOUR_IQP_API_TOKEN>\")"
+    "      If you accidentally share your token with someone or include it in version control like Git, immediately revoke your token by expiring it on the [IBM Quantum Platform dashboard](https://quantum.ibm.com/) (click the refresh button in the API token field) to reduce risk.\n",
+    "    </Admonition>"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "5154cbea-ccfa-42ea-a9ef-c31699c3b2c0",
    "metadata": {},
    "source": [
-    "Once you have authenticated, you can list the functions from the Qiskit Functions Catalog that you have access to:"
+    "4. Once you have authenticated, you can list the functions from the Qiskit Functions Catalog that you have access to:"
    ]
   },
   {

diff --git a/docs/guides/hello-world.ipynb b/docs/guides/hello-world.ipynb
@@ -221,7 +221,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "9a901271",
    "metadata": {},
    "outputs": [
@@ -242,8 +242,9 @@
    "source": [
     "from qiskit_ibm_runtime import QiskitRuntimeService\n",
     "\n",
-    "# If you did not previously save your credentials, use the following line instead:\n",
-    "# service = QiskitRuntimeService(channel=\"ibm_quantum\", token=\"<MY_IBM_QUANTUM_TOKEN>\")\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/setup-channel#iqp\n",
+    "# to authenticate with your API token.\n",
     "service = QiskitRuntimeService()\n",
     "\n",
     "backend = service.least_busy(simulator=False, operational=True)\n",
@@ -557,16 +558,18 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": null,
    "id": "428f05e7",
    "metadata": {},
    "outputs": [],
    "source": [
     "from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager\n",
     "from qiskit_ibm_runtime import QiskitRuntimeService\n",
     "\n",
-    "# If you did not previously save your credentials, use the following line instead:\n",
-    "# service = QiskitRuntimeService(channel=\"ibm_quantum\", token=\"<MY_IBM_QUANTUM_TOKEN>\")\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/setup-channel#iqp\n",
+    "# to authenticate with your API token.\n",
+    "\n",
     "service = QiskitRuntimeService()\n",
     "\n",
     "backend = service.least_busy(\n",

diff --git a/docs/guides/multiverse-computing-singularity.ipynb b/docs/guides/multiverse-computing-singularity.ipynb
@@ -1,20 +1,20 @@
 {
  "cells": [
   {
-    "cell_type": "code",
-    "execution_count": null,
-    "id": "613c4d93",
-    "metadata": {
-        "tags": [
-        "remove-cell"
-        ]
-    },
-    "outputs": [],
-    "source": [
-        "# This cell is hidden from users\n",
-        "# It stops the linter complaining about undefined variables\n",
-        "# ruff: noqa: F821"
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "613c4d93",
+   "metadata": {
+    "tags": [
+     "remove-cell"
     ]
+   },
+   "outputs": [],
+   "source": [
+    "# This cell is hidden from users\n",
+    "# It stops the linter complaining about undefined variables\n",
+    "# ruff: noqa: F821"
+   ]
   },
   {
    "cell_type": "markdown",
@@ -590,8 +590,11 @@
     "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
     "\n",
     "# authentication\n",
-    "client = IBMServerlessClient(token=\"<YOUR_IQP_API_TOKEN>\")\n",
-    "catalog = QiskitFunctionsCatalog(token=\"<YOUR_IQP_API_TOKEN>\")\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/functions\n",
+    "# to authenticate with your API token.\n",
+    "client = IBMServerlessClient()\n",
+    "catalog = QiskitFunctionsCatalog()\n",
     "\n",
     "# load function\n",
     "singularity = catalog.load(\"multiverse/singularity\")"

diff --git a/docs/guides/q-ctrl-optimization-solver.ipynb b/docs/guides/q-ctrl-optimization-solver.ipynb
@@ -130,14 +130,15 @@
    "source": [
     "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
     "\n",
-    "# Credentials\n",
-    "token = \"<YOUR_IQP_API_TOKEN>\"\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/setup-channel#iqp\n",
+    "# to authenticate with your API token.\n",
     "hub = \"<YOUR_IQP_HUB>\"\n",
     "group = \"<YOUR_IQP_GROUP>\"\n",
     "project = \"<YOUR_IQP_PROJECT>\"\n",
     "\n",
     "# Authentication\n",
-    "catalog = QiskitFunctionsCatalog(token=token)\n",
+    "catalog = QiskitFunctionsCatalog()\n",
     "\n",
     "# Access Function\n",
     "solver = catalog.load(\"q-ctrl/optimization-solver\")"

diff --git a/docs/guides/q-ctrl-performance-management.ipynb b/docs/guides/q-ctrl-performance-management.ipynb
@@ -100,14 +100,15 @@
    "source": [
     "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
     "\n",
-    "# Credentials\n",
-    "token = \"<YOUR_IQP_API_TOKEN>\"\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/functions\n",
+    "# to authenticate with your API token.\n",
     "hub = \"<YOUR_IQP_HUB>\"\n",
     "group = \"<YOUR_IQP_GROUP>\"\n",
     "project = \"<YOUR_IQP_PROJECT>\"\n",
     "\n",
     "# Authentication\n",
-    "catalog = QiskitFunctionsCatalog(token=token)\n",
+    "catalog = QiskitFunctionsCatalog()\n",
     "\n",
     "# Access Function\n",
     "perf_mgmt = catalog.load(\"q-ctrl/performance-management\")"

diff --git a/docs/guides/qedma-qesem.ipynb b/docs/guides/qedma-qesem.ipynb
@@ -99,7 +99,10 @@
     "\n",
     "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
     "\n",
-    "catalog = QiskitFunctionsCatalog(token=\"<YOUR_IQP_API_TOKEN>\")\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/functions\n",
+    "# to authenticate with your API token.\n",
+    "catalog = QiskitFunctionsCatalog()\n",
     "\n",
     "qesem_function = catalog.load(\"qedma/qesem\")"
    ]

diff --git a/docs/guides/qunasys-quri-chemistry.ipynb b/docs/guides/qunasys-quri-chemistry.ipynb
@@ -58,6 +58,9 @@
    "source": [
     "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n",
     "\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/functions\n",
+    "# to authenticate with your API token.\n",
     "catalog = QiskitFunctionsCatalog()\n",
     "\n",
     "function = catalog.load(\"qunasys/quri-chemistry\")"

diff --git a/docs/guides/serverless-first-program.ipynb b/docs/guides/serverless-first-program.ipynb
@@ -175,7 +175,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "id": "7077ba00-1571-4f99-8c53-b1a9ac280987",
    "metadata": {},
    "outputs": [
@@ -192,6 +192,9 @@
     "\n",
     "from qiskit_ibm_runtime import QiskitRuntimeService\n",
     "\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/setup-channel#iqp\n",
+    "# to authenticate with your API token.\n",
     "service = QiskitRuntimeService(channel=\"ibm_quantum\")\n",
     "backend = service.backend(backend_name)"
    ]

diff --git a/docs/guides/serverless-manage-resources.ipynb b/docs/guides/serverless-manage-resources.ipynb
@@ -76,7 +76,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "id": "475d82f0-15cc-4db3-b3b0-54b07822b2a0",
    "metadata": {},
    "outputs": [
@@ -95,6 +95,9 @@
     "from qiskit_ibm_runtime import QiskitRuntimeService\n",
     "from qiskit_serverless import distribute_task\n",
     "\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/setup-channel#iqp\n",
+    "# to authenticate with your API token.\n",
     "service = QiskitRuntimeService()\n",
     "\n",
     "@distribute_task(target={\"cpu\": 1})\n",
@@ -213,9 +216,9 @@
    "execution_count": 6,
    "id": "df28a92c-3585-49f0-a2ea-828a34638684",
    "metadata": {
-     "tags": [
-       "remove-cell"
-     ]
+    "tags": [
+     "remove-cell"
+    ]
    },
    "outputs": [
     {
@@ -493,7 +496,7 @@
     "\n",
     "<Admonition type=\"info\" title=\"Recommendations\">\n",
     "\n",
-    "- See a full example that [ports existing code to Qiskit Serverless ](./serverless-port-code).\n",
+    "- See a full example that [ports existing code to Qiskit Serverless](./serverless-port-code).\n",
     "- Read a paper in which researchers used Qiskit Serverless and quantum-centric supercomputing to [explore quantum chemistry](https://arxiv.org/abs/2405.05068v1).\n",
     "\n",
     "</Admonition>"

diff --git a/docs/guides/serverless-port-code.mdx b/docs/guides/serverless-port-code.mdx
@@ -19,8 +19,10 @@ from qiskit.circuit.random import random_circuit
 qc_random = [(random_circuit(20, 20, measure=True)) for _ in range(30)]
 optimization_level = 3
 
-# Get backend
-service = QiskitRuntimeService(channel="ibm_quantum", token=API_TOKEN)
+# If you have not previously saved your credentials, follow instructions at
+# https://docs.quantum.ibm.com/guides/setup-channel#iqp
+# to authenticate with your API token.
+service = QiskitRuntimeService(channel="ibm_quantum")
 backend = service.get_backend(backend_name)
 
 pass_manager = generate_preset_pass_manager(
@@ -72,6 +74,7 @@ def transpile_parallel(circuit, pass_manager):
 
 try:
     # Get backend
+    # Follow instructions at https://docs.quantum.ibm.com/guides/setup-channel#iqp to authenticate with your API token.
     service = QiskitRuntimeService(channel="ibm_quantum")
     backend = service.get_backend(backend_name)
 
@@ -101,13 +104,13 @@ except Exception as e:
 
 ## Upload to Qiskit Serverless
 
+Follow the instructions on the [Introduction to Qiskit Functions](/guides/functions) page to authenticate with your API token.
+
 ```python
 from qiskit_ibm_catalog import QiskitServerless, QiskitFunction
 
-# Authenticate to the remote cluster and submit the pattern for remote execution
-serverless = QiskitServerless(
-    token=API_TOKEN
-)
+# Authenticate to the remote cluster and submit the pattern for remote execution.
+serverless = QiskitServerless() 
 
 transpile_remote_demo = QiskitFunction(
     title="transpile_remote_serverless",

diff --git a/docs/guides/serverless-run-first-workload.ipynb b/docs/guides/serverless-run-first-workload.ipynb
@@ -134,7 +134,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "ebefb5ac-c8a8-4350-b16f-0677f0e412e5",
    "metadata": {},
    "outputs": [
@@ -149,6 +149,9 @@
    "source": [
     "from qiskit_ibm_runtime import QiskitRuntimeService\n",
     "\n",
+    "# If you have not previously saved your credentials, follow instructions at\n",
+    "# https://docs.quantum.ibm.com/guides/setup-channel#iqp\n",
+    "# to authenticate with your API token.\n",
     "service = QiskitRuntimeService()\n",
     "backend = service.least_busy(operational=True, simulator=False)\n",
     "print(backend.name)"