Merge pull request snok#126 from Bryhn-Bjolgerud/Update-Django-AUTH-A…

…DFS-DOCS Update django azure ad config guide
mmcclelland1002 · Jan 18, 2021 · 7dfe8a8 · 7dfe8a8
2 parents 639715f + 67d7ac8
commit 7dfe8a8
Show file tree

Hide file tree

Showing 9 changed files with 72 additions and 80 deletions.
diff --git a/docs/_static/2021/01-azure_active_directory.png b/docs/_static/2021/01-azure_active_directory.png
diff --git a/docs/_static/2021/02-azure_dashboard.png b/docs/_static/2021/02-azure_dashboard.png
diff --git a/docs/_static/2021/03-new_registrations.png b/docs/_static/2021/03-new_registrations.png
diff --git a/docs/_static/2021/04-app_registrations_specs.png b/docs/_static/2021/04-app_registrations_specs.png
diff --git a/docs/_static/2021/05-application_overview.png b/docs/_static/2021/05-application_overview.png
diff --git a/docs/_static/2021/06-add_Secret.png b/docs/_static/2021/06-add_Secret.png
diff --git a/docs/_static/2021/07-add_Secret_name.png b/docs/_static/2021/07-add_Secret_name.png
diff --git a/docs/_static/2021/08-copy_Secret.png b/docs/_static/2021/08-copy_Secret.png
diff --git a/docs/azure_ad_config_guide.rst b/docs/azure_ad_config_guide.rst
@@ -7,142 +7,134 @@ itself, it might take some tries to get all settings right.
 This guide tries to give a basic overview of how to configure Azure AD and how to determine the settings for
 django-auth-adfs. Installing and configuring the basics of Azure AD is not explained here.
 
-* **Web server:** http://webserver.example.com
-
 
 Step 1 - Register an application
 --------------------------------
 
-Open the **Azure Active Directory** dashboard and click **Properties**.
-The **Directory ID** field contains the value for the :ref:`tenant_id_setting` setting.
+After signing in to `Azure <https://portal.azure.com>`_. Open the **Azure Active Directory** dashboard. 
 
-.. image:: _static/AzureAD/01-Azure_AD.png
+.. image:: _static/2021/01-azure_active_directory.png
    :scale: 50 %
 
 ------------
 
-Click **App registrations** and then **New application registration**.
-
-.. image:: _static/AzureAD/02-add_web_application.png
-   :scale: 50 %
 
-------------
+Note down your **Tenant_ID** you will need it later.
 
-Enter a name for the application, select **Web app / API** as type and fill in the URL of the main page of your website.
 
-.. image:: _static/AzureAD/03-add_web_application_settings.png
-   :scale: 50 %
+.. image:: _static/2021/02-azure_dashboard.png
+    :scale: 50 %
 
 ------------
 
-Click the **Manifest** button.
 
-* Change the value of ``groupMembershipClaims`` to ``"All"`` to add the claim with groups to the access token.
-* The value of ``identifierUris`` is the value for the :ref:`relying_party_id_setting` and
-  :ref:`audience_setting` setting.
+Navigate to **App Registrations**, then click **New registration** in the upper left hand corner.
 
-Click the **Save** button to save the settings.
 
-.. image:: _static/AzureAD/04-add_web_application_manifest.png
-   :scale: 50 %
+.. image:: _static/2021/03-new_registrations.png
+    :scale: 50 %
 
 ------------
 
-Use the breadcrumbs at the top to navigate back to **App registration** and click the **New application registration**
-button again.
 
-.. image:: _static/AzureAD/05-add_native_application.png
-   :scale: 50 %
+Here you register your application. 
 
-------------
+1. The display name of your application. 
+2. What type of accounts can access your application.
+3. Here you need to add allowed redirect URIs. The Redirect URI value must match with the domain where your Django application is located(*eg. http://localhost:8000/oauth2/callback*).
 
-Fill in a name again an this time select the **Native** type.
 
-The **Redirect URI** value must match with the domain where your Django application is located and the patch where you
-mapped the ``django_auth_adfs`` urls in your ``urls.py`` file. If you follow the installation steps from this
-documentation, this should be something like ``https://your.domain.com/oauth2/callback``.
-
-.. image:: _static/AzureAD/06-add_native_application_settings.png
-   :scale: 50 %
+.. image:: _static/2021/04-app_registrations_specs.png
+    :scale: 50 %
 
 ------------
 
-The value of ``Application ID`` is the value for the :ref:`client_id_setting` setting.
 
-The native application now needs to be given permission to access the web application we created earlier.
-Click the **Settings** button and then select **Required permissions**
+When done registering, you will be redirected to your applications overview. Here you need to note down your **Client_ID**. This is how your Django project finds the right Azure application.  
 
-.. image:: _static/AzureAD/07-add_native_application_settings.png
-   :scale: 50 %
+
+.. image:: _static/2021/05-application_overview.png
+    :scale: 50 %
 
 ------------
 
-Click **Add** and then **Select API**
 
-.. image:: _static/AzureAD/08-add_native_application_settings.png
-   :scale: 50 %
+Next we need to generate a **Client_Secret**. Your application will use this to prove its identity when requesting a token. 
+
+
+.. image:: _static/2021/06-add_Secret.png
+    :scale: 50 %
 
 ------------
 
-Search for your web application (it won't show by default), select it from the list and click the **Select** button.
 
-.. image:: _static/AzureAD/09-add_native_application_permissions.png
-   :scale: 50 %
+Give it a short name. It is not important what it is, only used by you, to better keep track of them incase you make more.
+
+
+.. image:: _static/2021/07-add_Secret_name.png
+    :scale: 50 %
 
 ------------
 
-Click **Select Permissions**, check the checkbox in front of the web application and click the **Select** button.
 
-.. image:: _static/AzureAD/10-add_native_application_permissions.png
-   :scale: 50 %
+It will be become hidden after a short time, so be sure to note this one down quick.
+
+
+.. image:: _static/2021/08-copy_Secret.png
+    :scale: 50 %
 
 ------------
 
-As a final step, click the **Grant permissions** button and confirm with **Yes**.
 
-.. image:: _static/AzureAD/11-add_native_application_apply_permissions.png
-   :scale: 50 %
+
+Step 2 - Configuring settings.py
+--------------------------------------------------------
+We need to update the ``settings.py`` to accomedate for our registered Azure AD application. 
 
-Step 2 - Configuring Claims
----------------------------
+Replace your AUTH_ADFS with this.
 
-Except for the groups claim we configure earlier, there isn't much we can configure on Azure AD.
+.. code-block:: python
 
-The :ref:`claim_mapping_setting`, :ref:`groups_claim_setting` and :ref:`username_claim_setting` settings are all
-automatically set when you configure the :ref:`tenant_id_setting` setting.
+    # Client secret is not public information. Should store it as an environment variable.
+    
+    client_id = 'Your client id here'
+    cient_secret = 'Your client secret here'
+    tenant_id = 'Your tenant id here'
+    
 
-It boils down to these settings:
+    AUTH_ADFS = {
+        'AUDIENCE': client_id,
+        'CLIENT_ID': client_id,
+        'CLIENT_SECRET': cient_secret,
+        'CLAIM_MAPPING': {'first_name': 'given_name',
+                          'last_name': 'family_name',
+                          'email': 'upn'},
+        'GROUPS_CLAIM': 'roles',
+        'MIRROR_GROUPS': True,
+        'USERNAME_CLAIM': 'upn',
+        'TENANT_ID': tenant_id,
+        'RELYING_PARTY_ID': client_id,
+    }
+    
 
-.. code-block:: python
+Add this to your AUTHENTICATION_BACKENDS.
 
-    USERNAME_CLAIM = "upn"
-    GROUPS_CLAIM = "groups"
-    CLAIM_MAPPING = {"first_name": "given_name",
-                     "last_name": "family_name",
-                     "email": "email"}
+.. code-block:: python
 
-Step 3 - Determine configuration settings
------------------------------------------
+    AUTHENTICATION_BACKENDS = [
+        ...
+        'django_auth_adfs.backend.AdfsAccessTokenBackend',
+        ...
+    ]
 
-A quick recap of which Azure AD values relate to which settings.
 
-+---------------------------------------+-------------------------------+
-| LDAP Attribute                        | Outgoing Claim Type           |
-+=======================================+===============================+
-| Directory ID                          | TENANT_ID                     |
-+---------------------------------------+-------------------------------+
-| Native app's Application ID           | CLIENT_ID                     |
-+---------------------------------------+-------------------------------+
-| Web app / API it's ``identifierUris`` | RELYING_PARTY_ID and AUDIENCE |
-+---------------------------------------+-------------------------------+
 
-If you followed this guide, you should end up with a configuration like this.
+Add this path to your projects ``urls.py`` file.
 
 .. code-block:: python
 
-    AUTH_ADFS = {
-        "TENANT_ID": "12345678-90ab-cdef-1234-567890abcdef",
-        "CLIENT_ID": "480499d2-1f78-4a58-b7bc-03ebf8780af3",
-        "RELYING_PARTY_ID": "https://examplecom.onmicrosoft.com/338d463b-b82f-490b-567890abcdef",
-        "AUDIENCE": "https://examplecom.onmicrosoft.com/338d463b-b82f-490b-567890abcdef",
-    }
+    urlpatterns = [
+        ...
+        path('oauth2/', include('django_auth_adfs.drf-urls')),
+        ...
+    ]