extract installation.md

Doug Mahugh · Doug Mahugh · commit 3fe631497318 · 2017-11-30T07:56:19.000-08:00
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ This repo includes examples of four different approaches you can use to authenti
 
 * [Sample architecture](#sample-architecture)
 * [Python auth options](#python-auth-options)
-* [Using the samples](#using-the-samples)
+* [Running the samples](#running-the-samples)
 * [Contributing](#contributing)
 * [Resources](#resources)
 
@@ -54,26 +54,25 @@ If you're using [Requests](http://docs.python-requests.org/en/master/), the most
 
 If you're interested in developing your own authentication module, or are curious about the details of implementing OAuth 2.0 authentication for a web application, the [sample_graphrest.py](https://github.com/microsoftgraph/python-sample-auth/blob/master/sample_graphrest.py) sample provides an example of authenticating with [graphrest](https://github.com/microsoftgraph/python-sample-auth/blob/master/graphrest.py), a custom auth library written in Python. Note that this sample uses the [Bottle](https://bottlepy.org/docs/dev/) web framework, although it is relatively easy to port it to Flask or any other web framework that supports redirects and provides access to request query parameters.
 
-## Using the samples
+## Running the samples
 
-The following instructions take you through the steps required to install, configure, and run the samples.
+To install and configure the samples in this repo, see the instructions in [Installing the Python REST samples](blob/master/installation.md). These samples only require **User.Read** permission, which is the default, so you don't need to specify additional permissions while registering the application.
 
-### Prerequisites
+After you've completed those steps, follow these steps to run the samples:
 
-Before installing the sample:
+1. To start a sample, run the command ```python <progname>``` in the root folder of the cloned repo. For example, to run the ADAL sample, use this command: ```python sample_adal.py```.
 
-* Install Python from [https://www.python.org/](https://www.python.org/). We've tested the code with Python 3.6.2, but any Python 3.x version should work fine. If your code base is running under Python 2.7, you may find it helpful to use the [3to2](https://pypi.python.org/pypi/3to2) tools to port the code to Python 2.7.
-* To register your application for access to Microsoft Graph, you'll need either a [Microsoft account](https://www.outlook.com) or an [Office 365 for business account](https://msdn.microsoft.com/en-us/office/office365/howto/setup-development-environment#bk_Office365Account). If you don't have one of these, you can create a Microsoft account for free at [outlook.com](https://www.outlook.com).
+2. Go to this URL in a browser: [http://localhost:5000](http://localhost:5000). You should see a home page like this:
 
-### Installation
+![home page](static/images/homepage.png)
+
+3. Choose **Connect**, and then select your Microsoft account or Office 365 account and follow the instructions to log on. The first time you log on to the app under a particular identity, you will be prompted to consent to the permissions that the app is requesting. Choose **Accept**, which gives the application permission to read your profile information. You'll then see the following screen, which shows that the app has successfully authenticated and is able to read your profile information from Microsoft Graph:
 
-Follow these steps to install the samples:
+![sample output](static/images/graphcall.png)
 
-1. Clone this repo: ```git clone https://github.com/microsoftgraph/python-sample-auth.git```.
-2. Create and activate a virtual environment (optional). If you're new to Python virtual environments, [Miniconda](https://conda.io/miniconda.html) is a great place to start.
-3. In the root folder of your cloned repo, install the dependencies for the sample as listed in [requirements.txt](https://github.com/microsoftgraph/python-sample-auth/blob/master/requirements.txt) with this command: ```pip install -r requirements.txt```.
+### Python package dependencies
 
-Following the above steps will install all the dependencies for all four options. If you only plan to use one of the options, the following table lists the Python package dependencies for each sample.
+The requirements.txt file for this repo includes all of the packages for all of the auth samples. If you only plan to use one of the samples, you may prefer to only install the packages required for that sample. The following table lists the Python package dependencies for each sample.
 
 | Sample | Auth Library | Dependencies |
 | ------ | ------------ | ------------ |
@@ -82,46 +81,6 @@ Following the above steps will install all the dependencies for all four options
 | [sample_requests.py](https://github.com/microsoftgraph/python-sample-auth/blob/master/sample_requests.py) | [Requests-OAuthlib](https://github.com/requests/requests-oauthlib) | <ul><li>requests</li><li>requests-oauthlib</li><li>bottle</li></ul> |
 | [sample_graphrest.py](https://github.com/microsoftgraph/python-sample-auth/blob/master/sample_graphrest.py) | [graphrest module](https://github.com/microsoftgraph/python-sample-auth/blob/master/graphrest.py) | <ul><li>requests</li><li>bottle</li></ul> |
 
-### Configuration
-
-To configure the samples, you'll need to register a new application in the Microsoft [Application Registration Portal](https://apps.dev.microsoft.com/). You only need to do this once, and then any Microsoft identity can be used to run any of the samples.
-
-Follow these steps to register a new application:
-
-1. Sign in to the [Application Registration Portal](https://apps.dev.microsoft.com/) using either your personal or work or school account.
-
-2. Under **My applications**, choose **Add an app**. If you're using an Office 365 account and see two categories listed (Converged or Azure AD only), choose **Add an app** for the Converged applications section.
-
-3. Enter an application name, and choose **Create**. (Do *not* choose **Guided Setup**.)
-
-4. Next you'll see the registration page for your app. Copy and save the **Application Id** field.You will need it later to complete the configuration process.
-
-5. Under **Application Secrets**, choose **Generate New Password**. A new password will be displayed in the **New password generated** dialog. Copy this password. You will need it later to complete the configuration process.
-
-6. Under **Platforms**, choose **Add platform** > **Web**.
-
-7. Enter `http://localhost:5000/login/authorized` as the Redirect URL, and then choose **Save**.
-
-As the final step in configuring the sample, modify the [config.py](https://github.com/microsoftgraph/python-sample-auth/blob/master/config.py) file in the root folder of your cloned repo, and follow the instructions to enter your Client ID and Client Secret (which are referred to as Application Id and Password in the app registration portal). Then save the change, and you're ready to run the samples.
-
-### Running the samples
-
-To run one of the samples, run the command ```python <progname>``` in the root folder of the cloned repo. For example, to run the ADAL sample, use this command: ```python sample_adal.py```.
-
-Then go to this URL in a browser: [http://localhost:5000](http://localhost:5000)
-
-You should see a home page like this:
-
-![home page](static/images/homepage.png)
-
-Choose **Connect**, and then select your Microsoft account or Office 365 account and follow the instructions to log on.
-
-The first time you log on to the app under a particular identity, you will be prompted to consent to the permissions that the app is requesting. Choose **Accept**, which gives the application permission to read your profile information.
-
-You'll then see the following screen, which shows that the app has successfully read your profile information from Microsoft Graph:
-
-![sample output](static/images/graphcall.png)
-
 ## Contributing
 
 These samples are open source, released under the [MIT License](https://github.com/microsoftgraph/python-sample-auth/blob/master/LICENSE). Issues (including feature requests and/or questions about this sample) and [pull requests](https://github.com/microsoftgraph/python-sample-auth/pulls) are welcome. If there's another Python sample you'd like to see for Microsoft Graph, we're interested in that feedback as well &mdash; please log an [issue](https://github.com/microsoftgraph/python-sample-auth/issues) and let us know!
diff --git a/installation.md b/installation.md
@@ -0,0 +1,58 @@
+# Installing the Python REST samples
+
+This page covers how to install Python REST samples for Microsoft Graph. These instructions apply to the samples in these repos:
+
+* [Python authentication samples for Microsoft Graph](https://github.com/microsoftgraph/python-sample-auth)
+* [Working with paginated Microsoft Graph responses in Python](https://github.com/microsoftgraph/python-sample-pagination)
+
+## Prerequisites
+
+Before installing the sample:
+
+* Install Python from [https://www.python.org/](https://www.python.org/). We've tested the code with Python 3.6, but any Python 3.x version should work. If your code base is running under Python 2.7, you may find it helpful to use the [3to2](https://pypi.python.org/pypi/3to2) tools to port the code to Python 2.7.
+* To register your application for access to Microsoft Graph, you'll need either a [Microsoft account](https://www.outlook.com) or an [Office 365 for business account](https://msdn.microsoft.com/en-us/office/office365/howto/setup-development-environment#bk_Office365Account). If you don't have one of these, you can create a Microsoft account for free at [outlook.com](https://www.outlook.com).
+
+## Installation
+
+Follow these steps to install the samples:
+
+1. Clone the repo, using one of these commands:
+
+    ```git clone https://github.com/microsoftgraph/python-sample-auth.git```
+
+    ```git clone https://github.com/microsoftgraph/python-sample-pagination.git```
+
+2. Create and activate a virtual environment (optional). If you're new to Python virtual environments, [Miniconda](https://conda.io/miniconda.html) is a great place to start.
+3. In the root folder of your cloned repo, install the dependencies for the sample as listed in the ```requirements.txt``` file with this command: ```pip install -r requirements.txt```.
+
+## Configuration
+
+To configure the samples, you'll need to register a new application in the Microsoft [Application Registration Portal](https://apps.dev.microsoft.com/).
+
+Follow these steps to register a new application:
+
+1. Sign in to the [Application Registration Portal](https://apps.dev.microsoft.com/) using either your personal or work or school account.
+
+2. Under **My applications**, choose **Add an app**. If you're using an Office 365 account and see two categories listed (Converged or Azure AD only), choose **Add an app** for the Converged applications section.
+
+3. Enter an application name, and choose **Create**. (Do *not* choose **Guided Setup**.)
+
+4. Next you'll see the registration page for your app. Copy and save the **Application Id** field.You will need it later to complete the configuration process.
+
+5. Under **Application Secrets**, choose **Generate New Password**. A new password will be displayed in the **New password generated** dialog. Copy this password. You will need it later to complete the configuration process.
+
+6. Under **Platforms**, choose **Add platform** > **Web**.
+
+7. Under **Delegated Permissions**, add the permissions/scopes required for the sample, as covered in the sample's README. For example, the [send mail](https://github.com/microsoftgraph/python-sample-send-mail) sample requires **Mail.Read** permission. Some samples (such as the [auth samples](https://github.com/microsoftgraph/python-sample-auth)) only require the default **User.Read** permission, which is pre-selected for a new application registration, so for those you won't need to add any permissions.
+
+8. Enter `http://localhost:5000/login/authorized` as the Redirect URL, and then choose **Save**.
+
+As the final step in configuring the sample, modify the ```config.py``` file in the root folder of your cloned repo, and follow the instructions to enter your Client ID and Client Secret (which are referred to as Application Id and Password in the app registration portal). Then save the change, and you're ready to run the samples as covered in each sample's README.
+
+## Working with multiple samples
+
+If you're installing multiple Python REST samples, you can re-use the application registration and ```config.py``` file in most cases.
+
+Samples that use Microsoft ADAL for authentication require that all required permissions/scopes are added to the application in the Application Registration Portal. So if you're using ADAL for multiple samples, you can either register a separate app for each sample, or add all required permissions to a single registered application.
+
+Samples using the other auth options can take advantage of _incremental consent_, which means you don't need to add permissions to the application registration. You can edit the ```SCOPES``` setting in the ```config.py``` file to add any permissions required for each sample, and the user will be prompted to consent to these permissions with they log in to the sample app.
