How_to_use_the_Data_Lab_AuthManager.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "### How to use the Data Lab *Auth Manager* Service\n",
    "\n",
    "*Revised: May 7, 2017*\n",
    "\n",
    "This notebook documents how to use the Data Lab authorization system via the *Auth Manager* service. This can be done either from a Python script or from the command line using the <i>datalab</i> command.\n",
    "\n",
    "While most Data Lab services may be accessed anonymously, others require a valid user account in order to take advantage of resources such as <i>Virtual Storage</i> or <i>Compute Services</i>.  User accounts may be created on the main Data Lab website and are not discussed here.\n",
    "\n",
    "Assuming an account has been created, the <i><b>authClient</b></i> interface can be used to authenticate yourself to the Data Lab to obtain an identity token used to access the resources allocated to the account.  This is typically the first step in any notebook or application, the returned token is then passed to every other interface method that requires authenticated access to a resource or service.\n",
    "\n",
    "A complete summary of the *AuthManager* client interface is given below.\n",
    "\n",
    "***\n",
    "\n",
    "#### Example User Login \n",
    "\n",
    "Most notebooks will begin by importing whatever packages are required.  In this case we'll want to import the *authClient* interface from the *dl* (i.e. Data Lab) package.  The next step is to call the *login()* method with your account name and password to obtain an identity token:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Standard notebook imports\n",
    "from __future__ import print_function\n",
    "import getpass\n",
    "from dl import authClient, queryClient, storeClient"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Account Password: ········\n",
      "Login token:   demo00.1018.1018.$1$Orf0pq3.$Z8V7xvbuP/J5nZLzWr1rd0\n"
     ]
    }
   ],
   "source": [
    "# Login using your user name and password, validate the returned\n",
    "# token or else print the returned error message.\n",
    "token = authClient.login ('demo00',getpass.getpass('Account Password: '))\n",
    "if not authClient.isValidToken (token):\n",
    "    print ('Error: invalid user login (%s)' % token)\n",
    "else:\n",
    "    print (\"Login token:   %s\" % token)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "The `login()` method will return either a valid token or an error message.  By calling the `isValidToken()` method it is possible to trap any login errors in the task.  The use of the '*getpass*' function means passwords do not need to be exposed and notebooks can be shared more freely."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "<font color='red'><h4>Security Note</h4></font>\n",
    "\n",
    "<font color='green'>\n",
    "Once you have logged in successfully, an identity token is saved on the server running the application (the Jupyter notebook server in this case) and will be offered for subsequent logins when no password is provided.  This means that notebooks may be shared to use a valid account without sharing the password in the notebook.  You can use the `logout()` method (see below) to remove this token from the server manually, but as an added precaution, tokens will not be used on public notebook servers, and the password will <b>always</b> be required when attempting to login as some user other than the logged-in user on authenticated notebook servers.\n",
    "</font>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "New login token: anonymous.0.0.anon_access\n",
      "Is new token valid?  True\n"
     ]
    }
   ],
   "source": [
    "# An example of using the stored token to login to the Data Lab\n",
    "tok2 = authClient.login('anonymous')\n",
    "print ('New login token: %s' % tok2)\n",
    "print ('Is new token valid?  %s' % authClient.isValidToken (tok2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "#### Additional Interface Methods\n",
    "\n",
    "Users can check whether specific account information is correct:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Is \"demo00\" a valid user?  True\n",
      "Is \"foobar\" the current password?  False\n",
      "Do we have a valid login token?  True\n"
     ]
    }
   ],
   "source": [
    "print ('Is \"demo00\" a valid user?  %s' % authClient.isValidUser ('demo00'))\n",
    "print ('Is \"foobar\" the current password?  %s' % authClient.isValidPassword ('demo00','foobar'))\n",
    "print ('Do we have a valid login token?  %s' % authClient.isValidToken (token))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "Users can also check on their login status using either the account name or the current token:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Is user \"dldemo\" currently logged-in?  True\n",
      "Is my token currently logged-in:  True\n",
      "Is user \"Scooby\" currently logged-in?  False\n"
     ]
    }
   ],
   "source": [
    "print ('Is user \"dldemo\" currently logged-in?  %s' % authClient.isUserLoggedIn ('demo00'))\n",
    "print ('Is my token currently logged-in:  %s' % authClient.isTokenLoggedIn (token))\n",
    "print ('Is user \"Scooby\" currently logged-in?  %s' % authClient.isUserLoggedIn ('Scooby'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "#### Resetting the User Account Password\n",
    "\n",
    "An account password can be reset by presenting a valid token for the account, the account name and the new password.  If the password reset succeeds, a new identity token is returned to the task. A failed reset will return an error message so it is advisable to check the return value before overwriting the current token."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "New Login token: demo00.1018.1018.$1$7slQ.X1q$advE5DQHW6HRj5YMjvco9/\n",
      "Old Login token: demo00.1018.1018.$1$VTeulRMc$dQEMN8z7NnKiPN9NsBhWW0\n",
      "Is new token currently logged in: True\n"
     ]
    }
   ],
   "source": [
    "new_token = authClient.passwordReset (token, 'demo00', 'datalab')\n",
    "if not authClient.isValidToken (new_token):\n",
    "    print ('Error: password reset failed (%s)' % new_token)\n",
    "else:\n",
    "    print ('New Login token: %s' % new_token)\n",
    "    print ('Old Login token: %s' % token)\n",
    "    \n",
    "print ('Is new token currently logged in: ' + authClient.isTokenLoggedIn (new_token))    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "We need to remember to reset the account password here so the next time we run the notebook we can login at the first cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Token:  demo00.1018.1018.$1$9Yqu24OU$oGZXANbgGTVUUYmsXGFyt0\n",
      "Is the reset token currently logged in: True\n",
      "Is the old reset token currently logged in: False\n"
     ]
    }
   ],
   "source": [
    "token = authClient.passwordReset (new_token, 'demo00', 'balatad')\n",
    "if not authClient.isValidToken (token):\n",
    "    print ('Error: password reset failed (%s)' % token)\n",
    "print ('Token:  %s' % token)\n",
    "print ('Is the reset token currently logged in: ' + authClient.isTokenLoggedIn (token)) \n",
    "print ('Is the old reset token currently logged in: ' + authClient.isTokenLoggedIn (new_token))\n",
    "\n",
    "# In order to run this cell multiple times, we'll reset the 'new_token' \n",
    "# so the next invocation of the reset works properly.\n",
    "new_token = token"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "#### Logging <i>Out</i> of the Data Lab\n",
    "\n",
    "The `logout()` method is used to log the user out of the Data Lab and remove the identity token from the server.  Strictly speaking, it is not required that an application log out once it is complete, subsequent logins will return the same identity token the next time you log in so long as it is still valid (e.g. you haven't logged out elsewhere)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Is token logged in: True\n",
      "Log out result = \"OK\"\n",
      "Is token logged in following logout(): False\n"
     ]
    }
   ],
   "source": [
    "# Log out the current user and remove the identity token.\n",
    "print ('Is token logged in: ' + authClient.isTokenLoggedIn (token))\n",
    "res = authClient.logout (token)\n",
    "print ('Log out result = \"%s\"'% res)\n",
    "print ('Is token logged in following logout(): ' + authClient.isTokenLoggedIn (token))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "### Example:  Anonymous Data Query\n",
    "\n",
    "All public data services may be accessed anonymously, when queried in this way data will always be returned immediately to the client.  When saving results to a Data Lab resource such as virtual storage, however, a valid user login token is required."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "raj2000_,dej2000_,actflag,mflag,bmag,rmag,epoch,raj2000,dej2000,id\n",
      "20:59:59.592,+35:16:03.27, , ,16.700001,15.1,1951.517,314.99829999999997,35.267575000000001,1200-16738677\n",
      "20:59:58.753,+35:16:04.59, , ,17.200001,16.299999,1951.517,314.99480299999999,35.267941999999998,1200-16737889\n",
      "21:00:01.230,+35:16:14.01, , ,19.700001,18.799999,1951.517,315.00512300000003,35.270558999999999,1200-16740156\n",
      "\n"
     ]
    }
   ],
   "source": [
    "anon_token = authClient.login ('anonymous')\n",
    "query = \"select * from usno.a2 limit 3\"\n",
    "response = queryClient.query (anon_token, adql=query, fmt='csv', output='foo.csv')\n",
    "print (response)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "source": [
    "### Example:  Saving Results to Virtual Storage\n",
    "\n",
    "Details of using the Virtual Storage system are described elsewhere, but in general the term *Virtual Storage* is used to refer to either a user's private database (their *MyDB*), or a remote file storage service that resides close to the data services.  *Virtual Storage* is used to allow workflows to be created that minimize the transfer of data.  \n",
    "\n",
    "#### Saving to the remote file storage\n",
    "\n",
    "Saving results to a file can be done by specifying the 'out' parameter in the form:\n",
    "\n",
    "`vos://<filename>`\n",
    "\n",
    "The `<filename>` must be unique for each query or else an error will be issued and the results will not be saved.  Therefore, good coding style would trap potential errors and handle it accordingly, e.g."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "OK\n"
     ]
    }
   ],
   "source": [
    "query = \"select * from usno.b1 limit 200\"\n",
    "try:\n",
    "    response = queryClient.query (token, adql=query, fmt='csv', \n",
    "                                  out='vos://mags.csv')\n",
    "except Exception as e:\n",
    "    # Handle any errors in the query.  By running this cell multiple times with the same\n",
    "    # output file, or by using a bogus SQL statement, you can view various error messages.\n",
    "    print (e.message)\n",
    "else:\n",
    "    if response is not None: \n",
    "        print (response)           # print the response\n",
    "    else:\n",
    "        print (\"OK\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "#### Saving to the user's remote database\n",
    "\n",
    "Similarly, results may be saved to a user's MyDB database by specifying a table name of the form:\n",
    "\n",
    "`mydb://<tablename>`\n",
    "\n",
    "As with filenames, the `<tablename>` must be unique."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "OK\n"
     ]
    }
   ],
   "source": [
    "query = \"select * from usno.b1 limit 1000\"\n",
    "try:\n",
    "    response = queryClient.query (token, adql=query, fmt='csv', \n",
    "                                  out='mydb://usno_test')\n",
    "except Exception as e:\n",
    "    # Handle any errors in the query.  By running this cell multiple times with the same\n",
    "    # output file, or by using a bogus SQL statement, you can view various error messages.\n",
    "    print (e.message)\n",
    "else:\n",
    "    if response is not None: \n",
    "        print (response)           # print the response\n",
    "    else:\n",
    "        print (\"OK\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "source": [
    "***\n",
    "\n",
    "### Auth Manager API Summary\n",
    "\n",
    "A summary of the complete *AuthManager* API is shown below:\n",
    "\n",
    "```\n",
    "LOGIN METHODS:\n",
    "--------------\n",
    "             token = login  (user, password=None, debug=False, verbose=False)\n",
    "               res =logout  (token)\n",
    "\n",
    "VALIDATION METHODS:\n",
    "-------------------\n",
    "            bval = isAlive  (svc_url=DEF_SERVICE_URL)\n",
    "       bval = isValidToken  (token)\n",
    "        bval = isValidUser  (user)\n",
    "    bval = isValidPassword  (user, password)\n",
    "\n",
    "ACCESS METHODS:\n",
    "---------------\n",
    "          bval = hasAccess  (user, resource)\n",
    "     bval = isUserLoggedIn  (user)\n",
    "    bval = isTokenLoggedIn  (token)\n",
    "\n",
    "ACCOUNT ADMIN METHODS:\n",
    "----------------------\n",
    " new_token = passwordReset  (token, username, password)\n",
    "\n",
    "         url = set_service  (svc_url)\n",
    "               get_service  ()\n",
    "\n",
    "               set_profile  (profile)\n",
    "profile_name = get_profile  ()\n",
    " prof_list = list_profiles  (token)\n",
    "\n",
    "To instantiate a Client object:\n",
    "\n",
    "    authClient = getClient  ()\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}