An all-in-one sample for Django web project

Author: rayluo

.env.sample

@@ -0,0 +1,30 @@
+# The following variables are required for the app to run.
+CLIENT_ID=<client id>
+CLIENT_SECRET=<client secret>
+
+# This sample can be configured as a Microsoft Entra ID app,
+# or a Microsoft Entra External ID app.
+
+# 1. If you are using a Microsoft Entra ID tenent,
+#    configure the AUTHORITY variable as
+#    "https://login.microsoftonline.com/TENANT_GUID"
+#    or "https://login.microsoftonline.com/subdomain.onmicrosoft.com".
+#
+#    Alternatively, use the ".../common" if you are building a multi-tenant AAD app
+#    in world-wide cloud
+AUTHORITY=https://login.microsoftonline.com/common
+#
+#
+# 2. If you are using a Microsoft Entra External ID for customers (CIAM) tenant,
+#    configure AUTHORITY as "https://subdomain.ciamlogin.com"
+#AUTHORITY=<authority url>
+
+REDIRECT_VIEW=getAToken  # Used for forming an absolute URL to your redirect URI.
+    # The absolute URL must match the redirect URI you set
+    # in the app's registration in the Azure portal.
+
+# You can use your own API's scope. Here we use a Microsoft Graph API as an example
+SCOPE=User.ReadBasic.All
+
+# The sample app will acquire a token to call this API
+ENDPOINT=https://graph.microsoft.com/v1.0/users  # This resource requires no admin consent

README.md

@@ -1,57 +1,185 @@
-# Project Name
+# Sample: A Python Django web project to sign in users and call APIs with the Microsoft Entra ID
 
-(short, 1-3 sentenced, description of the project)
+This is a Python web application that uses the
+[Django framework](https://www.djangoproject.com/)
+and the
+[Microsoft Entra ID](https://www.microsoft.com/security/business/microsoft-entra)
+to sign in users and make authenticated calls to the Microsoft Graph API.
 
-## Features
-
-This project framework provides the following features:
-
-* Feature 1
-* Feature 2
-* ...
 
 ## Getting Started
 
 ### Prerequisites
 
-(ideally very short, if any)
-
-- OS
-- Library version
-- ...
+- Register your web application in the Microsoft Entra admin center,
+  by following step 1, 2 and 3 of this
+  [Quickstart: Add sign-in with Microsoft to a Python web app](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-web-app-python-sign-in?tabs=windows)
+- Have [Python](https://python.org) 3.8+ installed
 
 ### Installation
 
-(ideally very short)
-
-- npm install [package name]
-- mvn install
-- ...
+1. This sample already implements sign-in and calling downstream API.
+   You can clone
+   [its repo](https://github.com/Azure-Samples/ms-identity-python-webapp-django)
+   or download its zip package, and then start using it or build on top of it.
+   (Alternatively, you can follow our [tutorial](#tutorial) to learn
+   how to build this from scratch, or how to add auth to your existing project.
+2. `cd project_name`
+3. Run `pip install -r requirements.txt` to install dependencies
+4. Run `python manage.py migrate` to initialize your Django project
+5. Copy [`.env.sample`](https://github.com/Azure-Samples/ms-identity-python-webapp-django/blob/main/.env.sample) as `.env`,
+   and then modify its content based on your application's registration.
 
 ### Quickstart
-(Add steps to get up and running quickly)
 
-1. git clone [repository clone url]
-2. cd [repository name]
-3. ...
+1. After finishing installation, now you can run
+   `python manage.py runserver localhost:5000` to start your development server.
+   You may need to change to a different port to match your redirect_uri setup.
+2. Now visit http://localhost:5000
+
+
+## Tutorial
+
+> Note: You do not have to read this tutorial.
+>
+> * If you are starting a new project, you can begin with
+>   [our sample](https://github.com/Azure-Samples/ms-identity-python-webapp-django)
+>   and build on top of it.
+
+The following chapters teach you
+how to build a Django project with Microsoft Entra ID from scratch.
+After that, you will also know how to modify an existing Python Django project
+to sign in users and call APIs with the Microsoft Entra ID.
+
+### Preface: Have a Django web project as a starting point
+
+You can use
+[Django's own tutorial, part 1](https://docs.djangoproject.com/en/5.0/intro/tutorial01/)
+as a reference. What we need are these steps:
+
+1. `django-admin startproject mysite`
+2. `python manage.py migrate`
+3. `python manage.py runserver localhost:5000`
+   You may need to change to a different port to match your redirect_uri setup.
+
+4. Now, add an `index` view to your project.
+   For now, it can simply return a "hello world" page to any visitor.
+
+   ```python
+   from django.http import HttpResponse
+   def index(request):
+       return HttpResponse("Hello, world. Everyone can read this line.")
+   ```
+
+### Chapter 1: Enable your Python Django web app to sign in users
+
+1. At the beginning of `mysite/settings.py` file, create a global Auth helper like this:
+
+   ```python
+   from identity.django import Auth
+   AUTH = Auth("your_client_id", client_credential=..., authority=..., redirect_view="xyz")
+   ```
+
+   Generally speaking, your redirect_uri shall contain a top-level path such as
+   `http://localhost:5000/redirect`,
+   then your setting here shall be `..., redirect_view="redirect")`.
+
+2. Inside the same `mysite/settings.py` file,
+   add `"identity",` into the `INSTALLED_APPS` list,
+   to enable the default templates came with the `identity` package.
+
+   ```python
+   INSTALLED_APPS = [
+    ...,
+    "identity",
+   ]
+   ```
+
+3. Modify the `mysite/urls.py` to add these content:
+
+   ```python
+   ...
+   from django.urls import path, include
+   from django.conf import settings
+
+   urlpatterns = [
+       path("", include(settings.AUTH.urlpatterns)),
+       ...
+   ]
+   ```
+
+4. Now, inside the `mysite/views.py`,
+   for each view that you would like to enforce user login,
+   simply add a one-liner `@settings.AUTH.login_required` before each view.
+   For example,
+
+   ```python
+   ...
+   from django.conf import settings
+
+   @settings.AUTH.login_required
+   def index(request):
+       return HttpResponse("Hello, if you can read this, you're signed in.")
+   ```
+
+   That is it. Now visit `http://localhost:5000` again, you will see the sign-in experience.
+
+
+### Chapter 2: Get an Access Token and call Microsoft Graph
+
+This chapter begins where chapter 1 left off.
+We will add the following new view which will call a downstream API.
+
+```python
+import json
+from django.shortcuts import redirect, render
+import requests
+
+...
+
+def call_downstream_api(request):
+    token = settings.AUTH.get_token_for_user(["your_scope1", "your_scope2"])
+    if "error" in token:
+        return redirect(settings.AUTH.login)
+    api_result = requests.get(  # Use access token to call downstream api
+        "https://example.com/your/api",
+        headers={'Authorization': 'Bearer ' + token['access_token']},
+        timeout=30,
+    ).json()  # Here we assume the response format is json
+    return render(request, 'display.html', {
+        "title": "Result of downstream API call",
+        "content": json.dumps(api_result, indent=4),
+    })
+```
+
+The `settings.AUTH.get_token_for_user(...)` will also implicitly enforce sign-in.
+
+You can refer to our
+[full sample here](https://github.com/Azure-Samples/ms-identity-python-webapp-django)
+to pick up other minor details, such as how to modify `urls.py` accordingly,
+and how to add templates for this new view (and for the existing `index()` view).
 
 
-## Demo
+### What is next?
 
-A demo app is included to show how to use the project.
+You may notice that, this sample's code base contains no templates used by sign-in.
+That is because the upstream helper library provides built-in minimalist templates.
+That is convenient, but at some point you may want to customize the look-and-feel.
+You can do so by copying
+[the upstream templates](https://github.com/rayluo/identity/tree/dev/identity/templates/identity)
+into your own project's `templates/identity` sub-directory, and then start hacking.
 
-To run the demo, follow these steps:
 
-(Add steps to start up the demo)
+## Contributing
 
-1.
-2.
-3.
+If you find a bug in the sample, please raise the issue on [GitHub Issues](../../issues).
 
-## Resources
+If you'd like to contribute to this sample, see [CONTRIBUTING.MD](/CONTRIBUTING.md).
 
-(Any additional resources or related projects)
+This project has adopted the
+[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information, see the
+[Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+or contact [[email protected]](mailto:[email protected])
+with any additional questions or comments.
 
-- Link to supporting information
-- Link to similar sample
-- ...

mysite/settings.py

@@ -9,9 +9,20 @@
 For the full list of settings and their values, see
 https://docs.djangoproject.com/en/4.2/ref/settings/
 """
-import os, random, string
 from pathlib import Path
 
+import os, random, string
+from dotenv import load_dotenv
+from identity.django import Auth
+load_dotenv()
+AUTH = Auth(
+    os.getenv('CLIENT_ID'),
+    client_credential=os.getenv('CLIENT_SECRET'),
+    redirect_view=os.getenv('REDIRECT_VIEW'),
+    scopes=os.getenv('SCOPE', "").split(),
+    authority=os.getenv('AUTHORITY'),
+    )
+
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = Path(__file__).resolve().parent.parent
 
@@ -37,6 +48,7 @@
     'django.contrib.sessions',
     'django.contrib.messages',
     'django.contrib.staticfiles',
+    "identity",  # To utilize the default templates came with the identity package
 ]
 
 MIDDLEWARE = [
@@ -54,7 +66,12 @@
 TEMPLATES = [
     {
         'BACKEND': 'django.template.backends.django.DjangoTemplates',
-        'DIRS': [],
+        'DIRS': [
+            BASE_DIR / "templates",  # Enable this project's templates folder.
+                # You can also add your own "identity/login.html" and
+                # "identity/auth_error.html" into this folder
+                # to override the default templates came with identity package.
+        ],
         'APP_DIRS': True,
         'OPTIONS': {
             'context_processors': [

mysite/urls.py

@@ -15,8 +15,15 @@
     2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
 """
 from django.contrib import admin
-from django.urls import path
+from django.urls import path, include
+from django.conf import settings
+
+from . import views
+
 
 urlpatterns = [
+    path("", include(settings.AUTH.urlpatterns)),
+    path('', views.index, name="index"),
+    path("call_downstream_api", views.call_downstream_api),
     path('admin/', admin.site.urls),
 ]

mysite/views.py

@@ -0,0 +1,39 @@
+import os
+import json
+
+from django.conf import settings
+from django.shortcuts import redirect, render
+import requests
+
+
+__version__ = "0.1.0"
+
+
+@settings.AUTH.login_required
+def index(request):
+    user = settings.AUTH.get_user(request)
+    assert user  # User would not be None since we decorated this view with @login_required
+    return render(request, 'index.html', dict(
+        user=user,
+        version=__version__,
+        edit_profile_url=settings.AUTH.get_edit_profile_url(request),
+        downstream_api=os.getenv("ENDPOINT"),
+    ))
+
+# We choose to not decorate this view with @login_required,
+# because its get_token_for_user() could ask for more scopes than initial login,
+# so we want to handle the error separately.
+def call_downstream_api(request):
+    token = settings.AUTH.get_token_for_user(request, os.getenv("SCOPE", "").split())
+    if "error" in token:
+        return redirect(settings.AUTH.login)
+    api_result = requests.get(  # Use access token to call downstream api
+        os.getenv("ENDPOINT"),
+        headers={'Authorization': 'Bearer ' + token['access_token']},
+        timeout=30,
+    ).json()  # Here we assume the response format is json
+    return render(request, 'display.html', {
+        "title": "Result of downstream API call",
+        "content": json.dumps(api_result, indent=4),
+    })
+

requirements.txt

@@ -1,3 +1,7 @@
 # Since we currently still supports Python 3.7, we choose Django version accordingly.
 # See https://docs.djangoproject.com/en/5.0/faq/install/#what-python-version-can-i-use-with-django
 django>=3.2,<6
+
+identity>=0.4,<0.5
+python-dotenv<0.22
+requests>=2,<3

templates/display.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>{{title}}</title>
+</head>
+<body>
+    <a href="javascript:window.history.go(-1)">Back</a> <!-- Displayed on top of a potentially long page, so it will remain visible -->
+    <h1>{{title}}</h1>
+    <pre>{{content}}</pre> <!-- Just a generic viewer to show the content as-is -->
+</body>
+</html>

templates/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Microsoft Entra ID Django Web App Sample: Index</title>
+</head>
+<body>
+    <h1>Microsoft Entra ID Django Web App Sample {{version}}</h1>
+    <h2>Welcome {{ user.name }}!</h2>
+
+    <ul>
+    {% if downstream_api %}
+      <li><a href='/call_downstream_api'>Call a downstream API</a></li>
+    {% endif %}
+
+    {% if edit_profile_url %}
+      <li><a href='{{ edit_profile_url }}'>Edit Profile</a></li>
+    {% endif %}
+
+    <li><a href="/logout">Logout</a></li>
+    </ul>
+</body>
+</html>
+