Merge pull request #227776 from pamelafox/ad-quickstart

Update the Python quickstart for Azure AD

Author: v-dirichards

articles/active-directory/develop/includes/web-app/quickstart-python.md

@@ -14,112 +14,99 @@ ms.author: cwerner
 ms.custom: aaddev, devx-track-python, scenarios:getting-started, languages:Python
 ---
 
-In this quickstart, you download and run a code sample that demonstrates how a Python web application can sign in users and get an access token to call the Microsoft Graph API. Users with a personal Microsoft Account or an account in any Azure Active Directory (Azure AD) organization can sign into the application.
+In this quickstart, you download and run a code sample that demonstrates how a Python web application can sign in users and call the Microsoft Graph API. Users with a personal Microsoft Account or an account in any Azure Active Directory (Azure AD) organization can sign into the application.
 
-See [How the sample works](#how-the-sample-works) for an illustration.
-
-## Prerequisites
-
-- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
-- [Python 2.7+](https://www.python.org/downloads/release/python-2713) or [Python 3+](https://www.python.org/downloads/release/python-364/)
-- [Flask](http://flask.pocoo.org/), [Flask-Session](https://pypi.org/project/Flask-Session/), [requests](https://requests.readthedocs.io/en/latest/)
-- [MSAL Python](https://github.com/AzureAD/microsoft-authentication-library-for-python)
+The following diagram displays how the sample app works:
 
+![Diagram that shows how the sample app generated by this quickstart works.](../../media/quickstart-v2-python-webapp/topology.png)
 
-## Register and download your quickstart app
+1. The application uses the [`identity` package](https://pypi.org/project/identity/) to obtain an access token from the Microsoft Identity platform.
+2. The access token is used as a bearer token to authenticate the user when calling the Microsoft Graph API.
 
-You have two options to start your quickstart application: express (Option 1), and manual (Option 2)
 
-### Option 1: Register and auto configure your app and then download your code sample
-
-1. Go to the <a href="https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/applicationsListBlade/quickStartType/PythonQuickstartPage/sourceType/docs" target="_blank">Azure portal - App registrations</a> quickstart experience.
-1. Enter a name for your application and select **Register**.
-1. Follow the instructions to download and automatically configure your new application.
+## Prerequisites
 
-### Option 2: Register and manually configure your application and code sample
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+- An Azure Active Directory (Azure AD) tenant. For more information on how to get an Azure AD tenant, see [how to get an Azure AD tenant.](/azure/active-directory/develop/quickstart-create-new-tenant)
+- [Python 3.7+](https://www.python.org/downloads/)
 
-#### Step 1: Register your application
+## Step 1: Register your application
 
-To register your application and add the app's registration information to your solution manually, follow these steps:
+Follow these steps to register your application in the Azure portal:
 
 1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a>.
 1. If you have access to multiple tenants, use the **Directory + subscription** filter :::image type="icon" source="../../media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to select the tenant in which you want to register an application.
-1. Under **Manage**, select **App registrations** > **New registration**.
-1. Enter a **Name** for your application, for example `python-webapp` . Users of your app might see this name, and you can change it later.
+1. Navigate to the portal's [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908) page, and select **New registration**.
+1. Enter a **Name** for your application, for example *python-webapp*. 
 1. Under **Supported account types**, select **Accounts in any organizational directory and personal Microsoft accounts**.
+1. Under **Redirect URIs**, select **Web** for the platform.
+1. Enter a redirect URI of `http://localhost:5000/getAToken`. This can be changed later.
 1. Select **Register**.
+
+## Step 2: Add a client secret
+
 1. On the app **Overview** page, note the **Application (client) ID** value for later use.
-1. Under **Manage**, select **Authentication**.
-1. Select **Add a platform** > **Web**.
-1. Add `http://localhost:5000/getAToken` as **Redirect URIs**.
-1. Select **Configure**.
 1. Under **Manage**, select the **Certificates & secrets** and from the **Client secrets** section, select **New client secret**.
-1. Type a key description (for instance app secret), leave the default expiration, and select **Add**.
-1. Note the **Value** of the **Client Secret** for later use.
+1. Enter a description for the client secret, leave the default expiration, and select **Add**.
+1. Save the **Value** of the **Client Secret** in a safe location. You'll need it to configure the code, and you can't retrieve it later.
+
+## Step 3: Add a scope
+
 1. Under **Manage**, select **API permissions** > **Add a permission**.
 1. Ensure that the **Microsoft APIs** tab is selected.
 1. From the *Commonly used Microsoft APIs* section, select **Microsoft Graph**.
-1. From the **Delegated permissions** section, ensure that the right permissions are checked: **User.ReadBasic.All**. Use the search box if necessary.
-1. Select the **Add permissions** button.
+1. From the **Delegated permissions** section, ensure that **User.ReadBasic.All** is selected. Use the search box if necessary.
+1. Select **Add permissions**.
 
-#### Step 2: Download your project
+## Step 4: Download the sample app
 
-[Download the Code Sample](https://github.com/Azure-Samples/ms-identity-python-webapp/archive/master.zip)
+[Download the Python code sample](https://github.com/Azure-Samples/ms-identity-python-webapp/archive/master.zip) or clone the repository:
 
+```powershell
+git clone https://github.com/Azure-Samples/ms-identity-python-webapp.git
+```
 
-#### Step 3: Configure the Application
+You can also use an integrated development environment to open the folder.
 
-1. Extract the zip file to a local folder closer to the root folder - for example, **C:\Azure-Samples**
-1. If you use an integrated development environment, open the sample in your favorite IDE (optional).
-1. Open the **app_config.py** file, which can be found in the root folder and replace with the following code snippet:
+## Step 5: Configure the sample app
 
-```python
-CLIENT_ID = "Enter_the_Application_Id_here"
-CLIENT_SECRET = "Enter_the_Client_Secret_Here"
-AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"
-```
-Where:
+1. Go to the application folder.
 
-- `Enter_the_Application_Id_here` - is the Application ID for the application you registered.
-- `Enter_the_Client_Secret_Here` - is the **Client Secret** you created in **Certificates & Secrets** for the application you registered.
-- `Enter_the_Tenant_Name_Here` - is the **Directory (tenant) ID** value of the application you registered.
+1. Create a *.env* file in the root folder of the project using *.env.sample* as a guide.
 
-#### Step 4: Run the code sample
+    ```python
+    TENANT_ID=<tenant id>
+    CLIENT_ID=<client id>
+    CLIENT_SECRET=<client secret>
+    ```
 
-1. You will need to install MSAL Python library, Flask framework, Flask-Sessions for server-side session management and requests using pip as follows:
+    * Set the value of `TENANT_ID` to the **Directory (tenant) ID** of the registered application, also available on the overview page.
+    * Set the value of `CLIENT_ID` to the **Application (client) ID** for the registered application, available on the overview page.
+    * Set the value of `CLIENT_SECRET` to the client secret you created in **Certificates & Secrets** for the registered application.
+    
+    The environment variables are referenced in *app_config.py*, and are kept in a separate *.env* file to keep them out of source control. The provided *.gitignore* file prevents the *.env* file from being checked in.
+
+## Step 6: Run the sample app
+
+1. Create a virtual environment for the app:
+
+    [!INCLUDE [Virtual environment setup](<../../../../app-service/includes/quickstart-python/virtual-environment-setup.md>)]
+
+1. Install the requirements using `pip`:
 
     ```shell
-    pip install -r requirements.txt
+    python3 -m pip install -r requirements.txt
     ```
 
-2. Run `app.py` from shell or command line:
+2. Run the app from the command line, specifying the host and port to match the redirect URI:
 
     ```shell
-    python app.py
+    python3 -m flask run --host=localhost --port=5000
     ```
 
    > [!IMPORTANT]
    > This quickstart application uses a client secret to identify itself as confidential client. Because the client secret is added as a plain-text to your project files, for security reasons, it is recommended that you use a certificate instead of a client secret before considering the application as production application. For more information on how to use a certificate, see [these instructions](../../active-directory-certificate-credentials.md).
 
-## More information
-
-### How the sample works
-![Shows how the sample app generated by this quickstart works](../../media/quickstart-v2-python-webapp/python-quickstart.svg)
-
-### Getting MSAL
-MSAL is the library used to sign in users and request tokens used to access an API protected by the Microsoft identity Platform.
-You can add MSAL Python to your application using Pip.
-
-```Shell
-pip install msal
-```
-
-### MSAL initialization
-You can add the reference to MSAL Python by adding the following code to the top of the file where you will be using MSAL:
-
-```Python
-import msal
-```
 
 [!INCLUDE [Help and support](../../../../../includes/active-directory-develop-help-support-include.md)]
 
@@ -129,3 +116,6 @@ Learn more about web apps that sign in users in our multi-part scenario series.
 
 > [!div class="nextstepaction"]
 > [Scenario: Web app that signs in users](../../scenario-web-app-sign-user-overview.md)
+
+> [!div class="nextstepaction"]
+> [Scenario: Web app that calls web APIs](../../scenario-web-app-call-api-overview.md)