Update documentation

.github/worfklows/linkchecker.yml

@@ -0,0 +1,31 @@
+name: Validate content links
+
+on:
+  push:
+  repository_dispatch:
+  workflow_dispatch:
+  schedule:
+    - cron: "00 18 * * *"
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Link Checker
+        id: lychee
+        uses: lycheeverse/lychee-action@v1.6.1
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+        with:
+          args: --verbose --exclude-file .lycheeignore --no-progress './**/*.md' --exclude-mail
+          fail: true
+
+      - name: Create Issue From File
+        if: always() && env.lychee_exit_code != 0 && github.event_name != 'pull_request'
+        uses: peter-evans/create-issue-from-file@v4
+        with:
+          title: Link Checker Report
+          content-filepath: ./lychee/out.md
+          labels: report, automated issue

README.md

@@ -1,3 +1,26 @@
+# Microsoft Authentication Library (MSAL) for Python Documentation
+
+[![Validate content links](https://github.com/MicrosoftDocs/microsoft-authentication-library-for-python/actions/workflows/linkchecker.yml/badge.svg)](https://github.com/MicrosoftDocs/microsoft-authentication-library-for-python/actions/workflows/linkchecker.yml)
+
+This is the documentation repository for Microsoft Authentication Library (MSAL) for .NET. If you are looking for the library, refer to [AzureAD/microsoft-authentication-library-for-python](https://github.com/AzureAD/microsoft-authentication-library-for-python).
+
+## Contributions
+
+Contributions to our documentation are welcome. Make sure to familiarize yourself with the [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/) and the [Contributor Guide](https://learn.microsoft.com/contribute/) before making any changes.
+
+> **Warning**
+> **Do not** modify any YML files in the `python/docs-ref-autogen` folder - those are generated automatically from the library source code and any changes will be automatically overwritten the next time the documentation Continuous Integration (CI) job runs. To make changes to any API docs you will need to open a pull request in the [AzureAD/microsoft-authentication-library-for-python](https://github.com/AzureAD/microsoft-authentication-library-for-python) repository.
+
+If you would like to author an entirely new document (e.g., for a new scenario), make sure to [open an issue](https://github.com/MicrosoftDocs/microsoft-authentication-library-for-python/issues) first. This will allow the engineering team to discuss the proposed changes and ensure that it won't be overwritten by future changes.
+
+## API reference documentation automation
+
+Continuous Integration (CI) jobs for this repository are available in the [automation Azure DevOps instance](https://apidrop.visualstudio.com/Content%20CI/_build?definitionId=5247).
+
+>**Note**
+>The changes from the CI job will always be pushed to the `smoke-test` branch first. To propagate them to production, merge the changes into `main`, and then merge `main` to `live`. Ensure that all checks pass before merging changes.
+
 ## Microsoft Open Source Code of Conduct
+
 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 [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

msal-python-conceptual/TOC.yml

@@ -5,8 +5,6 @@
     href: getting-started/why-use-msal-python.md
   - name: Register your app with Azure AD
     href: /azure/active-directory/develop/active-directory-integrating-applications
-  - name: Scenarios
-    href: getting-started/scenarios.md
   - name: Client applications
     href: getting-started/client-applications.md
   - name: Acquiring tokens

msal-python-conceptual/getting-started/acquiring-tokens.md

@@ -5,33 +5,34 @@ description: "There are many ways of acquiring a token. Some require user intera
 
 # Acquiring tokens
 
-As explained in [scenarios](./scenarios.md), there are many ways of acquiring a token. Some require user interaction through a web browser. Some don't require any user interaction.
-In general the way to acquire a token is different depending on the application type-  public client application (Desktop / Mobile) or a confidential client application (Web App, Web API, daemon application like a windows service)
+As explained in [MSAL Python usage scenarios](../index.md#usage-scenarios), there are many ways of acquiring a token. Some require user interaction through a web browser, while others don't require any user interaction at all.
 
 ## Prerequisites
 
-Before acquiring tokens with MSAL Python:
-
-- Instantiate a [client application](./client-applications.md)
+Before acquiring tokens with MSAL Python, make sure to instantiate a [client application](./client-applications.md)
 
 ## Token acquisition methods
 
-Follow the topics below for detailed explanation with MSAL Python code usage for each token acquisition method.
+The approach to acquiring a token is different depending on the application type -  public client applications (desktop and mobile) or confidential client application (web app, web API, or a daemon application like a Windows service). Each of the individual approaches is described below.
 
 ### Public client applications
 
-- Acquire tokens by [authorization code](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python#acquiring-a-token-interactively) after letting the user sign-in through the authorization request URL.
+Public client applications cannot securely store a secret and can _only_ authenticate the user that is interacting with the product. MSAL Python exposes most of the token acquisition logic for public applications through [`PublicClientApplication`](xref:msal.application.PublicClientApplication). Using this class enables developers to:
+
+- Acquire tokens **as the user** with the help of an [interactive flow](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python#acquiring-a-token-interactively) after letting the user sign-in through the authorization request URL.
 - It's also possible (but not recommended) to get a token with a [username and password](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python#username--password).
-- Finally, for applications running on devices which don't have a web browser, it's possible to acquire a token through the [device code flow](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python#command-line-tool-without-web-browser), which provides the user with a URL and a code. The user goes to a web browser on another device, enters the code and signs-in, and then Azure AD returns back a token to the browser-less device.
+- For applications running on devices which don't have a web browser, it's possible to acquire a token through the [device code flow](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python#command-line-tool-without-web-browser), which provides the user with a URL and a code. The user goes to a web browser on another device, enters the code and signs in. On successful authentication, Azure AD will return a token to the browser-less device.
 
 ### Confidential client applications
 
-- Acquire token **as the application itself** using [client credentials](/azure/active-directory/develop/scenario-daemon-acquire-token?tabs=python#acquiretokenforclient-api), and not for a user. For example, in apps which process users in batches and not a particular user such as in syncing tools.
-- In the case of Web Apps or Web APIs **calling another downstream Web API in the name of the user**, use the [On Behalf Of flow](/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) to acquire a token based on some User assertion (SAML for instance, or a JWT token).
-- **For Web apps in the name of a user**, acquire tokens by [authorization code](/azure/active-directory/develop/scenario-web-app-call-api-acquire-token?tabs=python) after letting the user sign-in through the authorization request URL. This is typically the mechanism used by an application which lets the user sign-in using Open ID Connect, but then wants to access Web APIs for this particular user.
+Confidential client applications can securely store a secret and can authenticate both on behalf of an application as well as on behalf of a given user. With MSAL Python, developers can use [`ConfidentialClientApplication`](xref:msal.application.ConfidentialClientApplication) to access confidential client application capabilities, such as:
+
+- Acquire token **as the application itself** using [client credentials](/azure/active-directory/develop/scenario-daemon-acquire-token?tabs=python#acquiretokenforclient-api), and not for a user. For example, this can be used in applications which process users in batches and not one particular user, such as syncing tools.
+- In the case of web Apps or web APIs **calling another downstream Web API in the name of the user**, use the [On Behalf Of flow](/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) to acquire a token based on a user assertion (e.g., SAML, JWT).
+- **For Web apps authenticating in the name of a user**, acquire tokens through [authorization code](/azure/active-directory/develop/scenario-web-app-call-api-acquire-token?tabs=python) after letting the user sign-in through the authorization request URL. This is typically the mechanism used by an application which lets the user sign-in using Open ID Connect but then wants to access Web APIs for this particular user.
 
-## MSAL Python caches tokens
+## MSAL Python token caching
 
-For both Public client and Confidential client applications, MSAL maintains a token cache, and applications should try to get a token from the cache first before any other means. Take a look at the [recommended pattern](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python) for token acquisition.
+Both public and confidential client applications support token caching, handled direclt by MSAL Python. Applications should try to get a token from the cache first before relying on any other means. Take a look at the [recommended token acquisition pattern](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python) to learn more.
 
-To be able to make use of the cache, the application needs to customize the [token cache serialization](/azure/active-directory/develop/msal-python-token-cache-serialization).
+To be able to persist the cache, the developers will need to configure the [token cache serialization](/azure/active-directory/develop/msal-python-token-cache-serialization) logic.

msal-python-conceptual/getting-started/client-applications.md

@@ -11,29 +11,33 @@ description: "How to instantiate client applications in MSAL Python."
 
 Before instantiating your app with MSAL Python:
 
-1. Understand the types of Client applications available- [Public Client and Confidential Client applications](/azure/active-directory/develop/msal-client-applications).
-1. You'll need to [register](/azure/active-directory/develop/quickstart-register-app) the application with Azure AD. You will therefore know:
-    - Its `client_id` (a string representing a GUID)
-    - The identity provider  URL (named the instance) and the sign-in audience for your application. These two parameters are collectively known as the authority.
-    - Possibly the `Tenant+id` in the case you are writing a line of business application (just for your organization, also named single-tenant application)
-    - In case it's a confidential client app, its application secret (`client_secret` string) or certificate
-    - For web apps, you'll have also set the `redirect_uri` where the identity provider will contact back your application with the security tokens.
+1. Understand the types of client applications available - [Public Client and Confidential Client applications](/azure/active-directory/develop/msal-client-applications).
+1. You'll need to [register the application](/azure/active-directory/develop/quickstart-register-app) with Azure AD. From the registration page, you will need:
+    - The application client identifier (a string in the form of a GUID)
+    - The identity provider URL (the instance) and the sign-in audience for your application. These two parameters are collectively known as the **authority**.
+    - If necessary, the tenant identifier (also a GUID) in case you are writing a line of business application scoped to just your organization (also known as a single-tenant application).
+    - If you are building a confidential client app, you will need to create an application secret in the form of a string or certificate.
+    - For web applications, you'll have also set the redirect URL that Azure AD will use to return the code.
 
 ### Instantiating a public client application
 
+Public client applications use the [`PublicClientApplication`](xref:msal.application.PublicClientApplication) class.
+
 ```python
 app = msal.PublicClientApplication(
-    config["client_id"],
-    authority=config["authority"],
+    "client_id",
+    authority="authority",
     )
 ```
 
 ### Instantiating a confidential client application
 
+Confidential client applications use the [`ConfidentialClientApplication`](xref:msal.application.ConfidentialClientApplication) class.
+
 ```python
 app = msal.ConfidentialClientApplication(
-        config["client_id"],
-        authority=config["authority"],
-        client_credential=config["client_secret"],
-        )
+    "client_id",
+    authority="authority",
+    client_credential="client_secret",
+    )
 ```