Merge pull request #190 from DavidJVitale/master

Working with different authentication schemes notebook update
thank you David.

Author: AtmaMani

guide/03-the-gis/working-with-different-authentication-schemes.ipynb

@@ -29,10 +29,8 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
-   "metadata": {
-    "collapsed": true
-   },
+   "execution_count": 3,
+   "metadata": {},
    "outputs": [],
    "source": [
     "# import the GIS class in gis module\n",
@@ -474,61 +472,114 @@
     "## Storing your credentialls locally\n",
     "If you are signing in frequently to a particular GIS and would like to store the credentials locally on your computer, then you could do so using the `profile` parameter of your `GIS`.\n",
     "\n",
-    "<blockquote>\n",
-    "This persisted profile for the GIS is stored in the users home directory in a config file named .arcgisprofile. The profile is <b>NOT ENCRYPTED</b> and you need to take care to protect the saved profile using operating system security or by other means. Once a profile has been saved, passing the profile parameter by itself uses the authorization credentials saved in the configuration file.\n",
-    "</blockquote>"
+    "Persistent profiles for the GIS can be created by giving the GIS authorization credentials and specifying a profile name. The profile stores all of the authorization credentials (except the password) in the user’s home directory in an unencrypted config file named `.arcgisprofile.` The profile securely stores the password in an O.S. specific password manager through the [keyring](https://pypi.python.org/pypi/keyring) python module. (Note: Linux systems may need additional software installed and configured for proper security) Once a profile has been saved, passing the profile parameter by itself uses the authorization credentials saved in the configuration file/password manager by that profile name. Multiple profiles can be created and used in parallel.\n"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Successfully logged in as: arcgis_python\n"
+      "profile defined for GIS @ https://python.playground.esri.com/portal\n",
+      "profile defined for GIS @ https://geosaurus.maps.arcgis.com\n"
      ]
     }
    ],
    "source": [
-    "gis = GIS(\"https://python.playground.esri.com/portal\", username='arcgis_python', password='amazing_arcgis_123',\n",
-    "          profile='python_playground_prof')\n",
-    "\n",
-    "print(\"Successfully logged in as: \" + gis.properties.user.username)"
+    "#Define 2 different profiles for two different urls\n",
+    "playground_gis = GIS(url=\"https://python.playground.esri.com/portal\", username='arcgis_python', password='amazing_arcgis_123',\n",
+    "                     profile='python_playground_prof')\n",
+    "agol_gis = GIS(url=\"https://arcgis.com/\", username='arcgis_python', password=\"P@ssword123\",\n",
+    "    profile=\"AGOL_prof\")\n",
+    "print(\"profile defined for {}\".format(playground_gis))\n",
+    "print(\"profile defined for {}\".format(agol_gis))"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "To sign in during a different session, simply specify the profile file name."
+    "To sign in during a different session, simply specify the profile file name. You can work with any number of connections concurrently, as the authentication credentials stored for each profile will be automatically loaded at runtime."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 24,
+   "execution_count": 21,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Successfully logged in as: arcgis_python\n"
+      "Successfully logged into 'python.playground.esri.com/portal' via the 'arcgis_python' user\n",
+      "Successfully logged into 'www.arcgis.com' via the 'arcgis_python' user\n"
      ]
     }
    ],
    "source": [
-    "gis2 = GIS(profile='python_playground_prof')\n",
-    "print(\"Successfully logged in as: \" + gis2.properties.user.username)"
+    "def print_profile_info(gis):\n",
+    "    print(\"Successfully logged into '{}' via the '{}' user\".format(\n",
+    "           gis.properties.portalHostname,\n",
+    "           gis.properties.user.username)) \n",
+    "\n",
+    "playground_gis = GIS(profile='python_playground_prof')\n",
+    "print_profile_info(playground_gis)\n",
+    "\n",
+    "agol_gis = GIS(profile=\"AGOL_prof\")\n",
+    "print_profile_info(agol_gis)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Persistent profiles details\n",
+    "Persistent profiles will store the any combination of the following ```GIS()``` parameters in the unencrypted `.arcgisprofile` file: \n",
+    "* ```url```\n",
+    "* ```username```\n",
+    "* ```key_file```\n",
+    "* ```cert_file```\n",
+    "* ```client_id```\n",
+    "\n",
+    "The ```password``` parameter (if specified) will be securely stored through the [keyring](https://pypi.python.org/pypi/keyring) module. This means that, behind the scenes, your password is retrieved at run-time from an operating system specific password store.\n",
+    "\n",
+    "### Windows\n",
+    "\n",
+    "On Windows, your password will be stored in the Windows Credentials Manager. You can access the Credentials Manager to manage stored passwords by selecting:\n",
+    "> Start > Control Panel > User Accounts > Credential Manager > Windows Credentials > Generic Credentials\n",
+    "\n",
+    "If you had a password stored through a profile named \"profile_example\", you would see this entry under \"arcgis_python_api_profile_passwords\":\n",
+    "\n",
+    "![](https://developers.arcgis.com/assets/img/python-graphics/persistent-profiles-example.png)\n",
+    "\n",
+    "Notice that in the Windows Credentials Manager's view, the profile name \"profile_example\" is filed under \"User name\".\n",
+    "\n",
+    "### macOS\n",
+    "\n",
+    "On macOS, your password will be stored in Keychain Access. You can access the Keychain to manage stored passwords by selecting:\n",
+    "\n",
+    "> Applications > Utilities > Keychain Access > Passwords > \"arcgis_python_api_profile_passwords\"\n",
+    "\n",
+    "### Linux\n",
+    "\n",
+    "On Linux, you may need additional software installed and configured to securely store passwords with persistent profiles. The Python executable running must have access over ```dbus``` to any of the following:\n",
+    "\n",
+    "* ```Freedesktop Secret Service``` / ```secretstorage``` for a GNOME environment\n",
+    "* ```KWallet``` for a KDE environment\n",
+    "* A custom configuration of the previous software packages and ```gnome-key-ring``` for a [headless environment](https://pypi.python.org/pypi/keyring#using-keyring-on-headless-linux-systems).\n",
+    "\n",
+    "Conda cannot use the ```dbus``` python module required for this, so it is best to install the ```arcgis``` package through the system-level python and pip. Read more about how to configure keyring on linux [on the keyring doc page](https://pypi.python.org/pypi/keyring#linux)."
    ]
   }
  ],
  "metadata": {
   "anaconda-cloud": {},
   "kernelspec": {
-   "display_name": "Python [default]",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -542,7 +593,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.5.2"
+   "version": "3.6.4"
   }
  },
  "nbformat": 4,