More docs on how to setup Redirect URI

This can reduce the misunderstanding which drove audience to use
low-level API.

Author: rayluo

README.md

@@ -30,7 +30,7 @@ This Identity library is an authentication/authorization library that:
   </tr>
 
   <tr>
-    <th>App Registration</th>
+    <th rowspan=2>App Registration</th>
     <td><!-- See https://github.com/github/cmark-gfm/issues/12 -->
 
 Following only the step 1, 2 and 3  of this
@@ -55,6 +55,26 @@ Following only the step 1 and 2 (including 2.1 and 2.2) of this
 </td>
   </tr>
 
+  <tr>
+    <td colspan=4>
+After app registration, you shall obtain the following information:
+
+* Your app's `client_id`, also known as application ID.
+  (For example, if you are using Entra ID, you may follow this
+  [app registration document](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app)).
+* Your app's credential, which can either be a secret string, or a certificate.
+  (For example, if you are using Entra ID, you may follow this
+  [app credential document](https://learn.microsoft.com/entra/identity-platform/how-to-add-credentials?tabs=client-secret)).
+  The `Identity` library's `client_credential` parameter supports all formats supported by
+  [`msal` library's same name parameter](https://msal-python.readthedocs.io/en/latest/#msal.ClientApplication.params.client_credential).
+* Your app's Redirect URI.
+  You may prepare two, one of them looks like `http://localhost:5000/redirect` for local development,
+  the other looks like `https://your_website.com/redirect` for your production.
+  (For example, if you are using Entra ID, you may follow this
+  [redirect URI document](https://learn.microsoft.com/entra/identity-platform/how-to-add-redirect-uri)).
+    </td>
+  </tr>
+
   <tr>
     <th>Web App Sign In & Sign Out</th>
     <td colspan=4>

docs/django.rst

@@ -35,9 +35,17 @@ Configuration
     from identity.django import Auth
     load_dotenv()
     AUTH = Auth(
+        # Instruction for these settings is available in this project's README file.
+        # https://github.com/rayluo/identity?tab=readme-ov-file#scenarios-supported
         os.getenv('CLIENT_ID'),
         client_credential=os.getenv('CLIENT_SECRET'),
-        redirect_uri=os.getenv('REDIRECT_URI'),
+        redirect_uri=
+            # Recommended to register and use a redirect_uri.
+            # It looks like http://localhost:5000/redirect for local development,
+            # or https://your_website.com/redirect for your production.
+            # If absent, Identity library will fall back to a Device Code mode.
+            os.getenv('REDIRECT_URI'),
+
         ...,  # See below on how to feed in the authority url parameter
         )
 

docs/flask.rst

@@ -40,9 +40,18 @@ Configuration
 
     auth = Auth(
         app,
+
+        # Instruction for these settings is available in this project's README file.
+        # https://github.com/rayluo/identity?tab=readme-ov-file#scenarios-supported
         os.getenv('CLIENT_ID'),
         client_credential=os.getenv('CLIENT_SECRET'),
-        redirect_uri=os.getenv('REDIRECT_URI'),
+        redirect_uri=
+            # Recommended to register and use a redirect_uri.
+            # It looks like http://localhost:5000/redirect for local development,
+            # or https://your_website.com/redirect for your production.
+            # If absent, Identity library will fall back to a Device Code mode.
+            os.getenv('REDIRECT_URI'),
+
         ...,  # See below on how to feed in the authority url parameter
         )
 

docs/quart.rst

@@ -25,9 +25,18 @@ Configuration
 
     auth = Auth(
         app,
+
+        # Instruction for these settings is available in this project's README file.
+        # https://github.com/rayluo/identity?tab=readme-ov-file#scenarios-supported
         os.getenv('CLIENT_ID'),
         client_credential=os.getenv('CLIENT_SECRET'),
-        redirect_uri=os.getenv('REDIRECT_URI'),
+        redirect_uri=
+            # Recommended to register and use a redirect_uri.
+            # It looks like http://localhost:5000/redirect for local development,
+            # or https://your_website.com/redirect for your production.
+            # If absent, Identity library will fall back to a Device Code mode.
+            os.getenv('REDIRECT_URI'),
+
         ...,  # See below on how to feed in the authority url parameter
         )
 

tox.ini

@@ -25,3 +25,8 @@ commands =
     mypy --install-types --non-interactive
     mypy {[tox]x_project_name}
 
+[testenv:docs]
+deps =
+    -r docs/requirements.txt
+commands =
+    sphinx-build docs docs/_build