{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from seeq import spy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# spy.login\n",
    "\n",
    "Logs into a Seeq Server with a set of credentials. This command is necessary if you are using the SPy module with your own installation of Jupyter, or with hosted Jupyter Notebook services like AWS SageMaker or Azure Notebooks.\n",
    "\n",
    "*Note: In Seeq Data Lab, you will log in using the normal Seeq Server landing page and your credentials will be used by the SPy module directly.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`spy.login(username=None, password=None, url=None, auth_provider='Seeq', ignore_ssl_errors=False, credentials_file=None)`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Specifying Seeq Server URL and credentials\n",
    "\n",
    "If you are not using Seeq Data Lab, you must specify the URL of the server. You can just copy the URL directly out of the browser's address box and use it. For example: `http://seeqserver:34216` or `https://mycompany.seeq.site`.\n",
    "\n",
    "You can choose to embed your credentials directly into the notebook using the `username` and `password` fields, or you can choose to specify `credentials_file` that is read from disk (username on first line, password on second line). Note that the credentials file is not secure: It just allows you to share your notebook without also supplying your credentials."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "spy.login(url='http://localhost:34216', username='mark.derbecker@seeq.com', password='DataLab!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Authentication Directories\n",
    "\n",
    "If your organization is configured to use LDAP or Windows Authentication where you have a corporate username and password, it may be necessary to specify the *authentication directory*. This is the name seen in the **Directory** dropdown on the Seeq login page, use it for the `directory` argument like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "spy.login(url='http://localhost:34216', username='mark.derbecker@seeq.com', password='DataLab!', directory='Seeq')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Access Keys\n",
    "\n",
    "If your organization uses OAuth 2 (e.g. Azure ActiveDirectory) single sign-on or password-less (e.g. smart card-based) Windows Authentication, you will need to use an Access Key to log in. Please read the [Access Key documentation](https://seeq.atlassian.net/wiki/spaces/KB/pages/740721558/Access+Keys) for information on how to create one. Once you have created the Access Key, use it like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "spy.login(url='http://localhost:34216', access_key='xk2wX9n5TSutTvrZzOTcSg', password='BUy8yFtE8kQ1gRS3n7XgTYr2C1K0FH')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In Seeq Server **R22.0.49.XX and earlier**, the Access Key is only valid for a set amount of time as specified in the server _Administation_ page's _Configuration_ tab, specifically the `Authentication/AccessKey/ValidityWithoutUserLogin` setting. The default is 1 day. The **validity time is measured from the time of last login**. If you have not logged out (it's important that you log out!) and then log back in to Seeq Workbench within the specified timeframe, you will need to do so to \"reset\" the validity period.\n",
    "\n",
    "In Seeq Server **R50.0.0 and later**, the Access Key validity period is more lenient. The validity expiration time is measured from the time that you closed all your active Seeq Workbench browser tabs. In other words, if you keep a Seeq Workbench tab open somewhere, your access key will remain valid, and once you close your tab, it will still remain valid for the time specified in the setting described above.\n",
    "\n",
    "If you wish to use an Access Key in conjunction with `credentials_file`, put the Access Key on the first line and the Password on the second line."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SSL Errors\n",
    "\n",
    "If you are using a secure connection (https), the root certificate in the SSL certificate chain used by the Seeq Server must be recognized by the Python `certifi` library. If not, you'll need to add `ignore_ssl_errors=True` with your `spy.login` call. Be warned that this will mean your connection is potentially insecure and vulnerable to man-in-the-middle attacks.\n",
    "\n",
    "If you are using Seeq Data Lab, you can potentially put the `seeq-key.pem` and `seeq-cert.pem` files from Seeq Server in Seeq Data Lab's `<global_folder>/keys` folder. The certificate file must contain the full unbroken certificate chain in order to work correctly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Proxy Servers\n",
    "\n",
    "If your organization uses a proxy server for Internet access, SPy will automatically look at the `HTTP_PROXY` and `HTTPS_PROXY` environment variables and use them if specified. Alternatively, you can supply an argument like `proxy='http://myproxyserver:8088'` to your `spy.login` call to specify it directly. If you specify `proxy=None`, then the `HTTP_PROXY` and `HTTPS_PROXY` environment variables will be ignored."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
