From 6262b824709c0f42a6a8428c55c5656fdf906103 Mon Sep 17 00:00:00 2001 From: Den <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:02:58 -0700 Subject: [PATCH 01/10] Add automation and update README --- .github/worfklows/linkchecker.yml | 31 +++++++++++++++++++++++++++++++ README.md | 25 ++++++++++++++++++++++++- 2 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 .github/worfklows/linkchecker.yml diff --git a/.github/worfklows/linkchecker.yml b/.github/worfklows/linkchecker.yml new file mode 100644 index 0000000..42c0e65 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/README.md b/README.md index 824a7c6..e46efc0 100644 --- a/README.md +++ b/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. \ No newline at end of file +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. From 98a704101ec71636e5bf70018c9ace754a4cfb91 Mon Sep 17 00:00:00 2001 From: Den <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:14:34 -0700 Subject: [PATCH 02/10] Clarify documentation --- .../getting-started/acquiring-tokens.md | 29 ++++++++++--------- .../getting-started/scenarios.md | 2 +- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/msal-python-conceptual/getting-started/acquiring-tokens.md b/msal-python-conceptual/getting-started/acquiring-tokens.md index f3e60b6..ed9ac3a 100644 --- a/msal-python-conceptual/getting-started/acquiring-tokens.md +++ b/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](./scenarios.md), 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 [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. - 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 that 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 use the cache, the developers will need to configure the [token cache serialization](/azure/active-directory/develop/msal-python-token-cache-serialization) logic. diff --git a/msal-python-conceptual/getting-started/scenarios.md b/msal-python-conceptual/getting-started/scenarios.md index 0e3dfb6..53597a0 100644 --- a/msal-python-conceptual/getting-started/scenarios.md +++ b/msal-python-conceptual/getting-started/scenarios.md @@ -3,7 +3,7 @@ title: Scenarios description: "MSAL Python can be used by applications to acquire tokens to access a protected API." --- -# Scenarios +# MSAL Python usage scenarios MSAL Python can be used by applications to acquire tokens to access a protected API. Tokens can be acquired by different **application types**: Desktop applications, Web applications, Web APIs, and applications running on devices that don't have a browser (such as IoT). In MSAL Python, applications are categorized as follows: From 6ec30f1bb6a7d9cadafc883014b8fd76a18534a2 Mon Sep 17 00:00:00 2001 From: Den <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:19:01 -0700 Subject: [PATCH 03/10] Consolidate scenarios docs --- msal-python-conceptual/TOC.yml | 2 -- .../getting-started/acquiring-tokens.md | 2 +- .../getting-started/scenarios.md | 26 ------------------- msal-python-conceptual/index.md | 25 +++++++++++++++++- 4 files changed, 25 insertions(+), 30 deletions(-) delete mode 100644 msal-python-conceptual/getting-started/scenarios.md diff --git a/msal-python-conceptual/TOC.yml b/msal-python-conceptual/TOC.yml index b01146f..ba41eef 100644 --- a/msal-python-conceptual/TOC.yml +++ b/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 diff --git a/msal-python-conceptual/getting-started/acquiring-tokens.md b/msal-python-conceptual/getting-started/acquiring-tokens.md index ed9ac3a..57f1225 100644 --- a/msal-python-conceptual/getting-started/acquiring-tokens.md +++ b/msal-python-conceptual/getting-started/acquiring-tokens.md @@ -5,7 +5,7 @@ description: "There are many ways of acquiring a token. Some require user intera # Acquiring tokens -As explained in [MSAL Python usage scenarios](./scenarios.md), 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. +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 diff --git a/msal-python-conceptual/getting-started/scenarios.md b/msal-python-conceptual/getting-started/scenarios.md deleted file mode 100644 index 53597a0..0000000 --- a/msal-python-conceptual/getting-started/scenarios.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Scenarios -description: "MSAL Python can be used by applications to acquire tokens to access a protected API." ---- - -# MSAL Python usage scenarios - -MSAL Python can be used by applications to acquire tokens to access a protected API. Tokens can be acquired by different **application types**: Desktop applications, Web applications, Web APIs, and applications running on devices that don't have a browser (such as IoT). In MSAL Python, applications are categorized as follows: - -- Public client applications (Desktop). These type of apps cannot store app secrets securely. -- Confidential client applications (Web apps, Web APIs, and daemon applications). These type of apps securely store a secret registered with Azure AD. - -Learn more details about instantiating and configuring the above in [Client applications](./client-applications.md) topic. -MSAL Python supports acquiring tokens either in the name of a user, or, in the name of the application itself (without a user). In the latter case, a confidential client application must be used. - -MSAL Python can be used in applications running on different operating systems (Windows, Linux, Mac). Scenarios might differ depending on the platform. - -Here are the key scenarios supported by MSAL Python. You can read the detailed explanations with MSAL Python code usage by following the links. - -- [Web application that signs in users](/azure/active-directory/develop/scenario-web-app-sign-user-overview) -- [Web Application signing in a user and calling a Web API in the name of the user](/azure/active-directory/develop/scenario-web-app-call-api-overview) (Note: MSAL only helps the Web Application to sign in and obtain tokens. To [protect a web API](/azure/active-directory/develop/scenario-protected-web-api-overview), you will need other libraries.) -- [Desktop application calling a Web API in the name of the signed-in user](/azure/active-directory/develop/scenario-desktop-overview) -- [Desktop/service daemon application calling Web API without a user](/azure/active-directory/develop/scenario-daemon-overview) -- [Application without a browser, or IOT application calling an API in the name of the user](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python#command-line-tool-without-web-browser) - -Can't find the scenario you are looking for? Check out the [supported scenarios and platforms](/azure/active-directory/develop/authentication-flows-app-scenarios#scenarios-and-supported-platforms-and-languages) across MSALs. diff --git a/msal-python-conceptual/index.md b/msal-python-conceptual/index.md index 791dea3..f916d28 100644 --- a/msal-python-conceptual/index.md +++ b/msal-python-conceptual/index.md @@ -72,4 +72,27 @@ Acquiring tokens with MSAL Python follows this 3-step pattern. This is the high print(result.get("error")) print(result.get("error_description")) print(result.get("correlation_id")) # You may need this when reporting a bug - ``` \ No newline at end of file + ``` + +# Usage scenarios + +MSAL Python can be used by applications to acquire tokens to access protected APIs. Tokens can be acquired by different **application types**: desktop applications, web applications, web APIs, and applications running on devices that don't have a browser (such as IoT devices). In MSAL Python, applications are categorized as follows: + +- **Public client applications (desktop and mobile)**. These types of apps cannot store app secrets securely. +- **Confidential client applications (web apps, web APIs, and daemon applications)**. These type of apps securely store a secret registered with Azure AD. + +Learn more about instantiating and configuring the above in the [Client applications](./client-applications.md) topic. + +MSAL Python supports acquiring tokens either in the name of a user or in the name of the application itself (without a user). In the latter case, a confidential client application must be used. + +MSAL Python can be used in applications running on different operating systems (Windows, Linux, macOS). + +Key scenarios supported by MSAL Python: + +- [Web application that signs in users](/azure/active-directory/develop/scenario-web-app-sign-user-overview) +- [Web Application signing in a user and calling a Web API in the name of the user](/azure/active-directory/develop/scenario-web-app-call-api-overview) (note that MSAL only helps the web application to sign in and obtain tokens. To [protect a web API](/azure/active-directory/develop/scenario-protected-web-api-overview), you will need other libraries). +- [Desktop application calling a Web API in the name of the signed-in user](/azure/active-directory/develop/scenario-desktop-overview) +- [Desktop/service daemon application calling Web API without a user](/azure/active-directory/develop/scenario-daemon-overview) +- [Application without a browser, or IOT application calling an API in the name of the user](/azure/active-directory/develop/scenario-desktop-acquire-token?tabs=python#command-line-tool-without-web-browser) + +Can't find the scenario you are looking for? Check out the [supported scenarios and platforms](/azure/active-directory/develop/authentication-flows-app-scenarios#scenarios-and-supported-platforms-and-languages) across MSAL libraries. \ No newline at end of file From 103bb04f91a604e25b54a89ce53e3f530ec2dc0b Mon Sep 17 00:00:00 2001 From: Den <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:25:01 -0700 Subject: [PATCH 04/10] Update client-applications.md --- .../getting-started/client-applications.md | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/msal-python-conceptual/getting-started/client-applications.md b/msal-python-conceptual/getting-started/client-applications.md index e83e88d..a3e198c 100644 --- a/msal-python-conceptual/getting-started/client-applications.md +++ b/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", + ) ``` From 752c5b16c599bdecc7a747f82f59aee2d501ece0 Mon Sep 17 00:00:00 2001 From: Den <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:30:34 -0700 Subject: [PATCH 05/10] Update index.md --- msal-python-conceptual/index.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/msal-python-conceptual/index.md b/msal-python-conceptual/index.md index f916d28..a570afd 100644 --- a/msal-python-conceptual/index.md +++ b/msal-python-conceptual/index.md @@ -5,31 +5,30 @@ description: "Get started with the Microsoft Authentication Library for Python t # Microsoft Authentication Library (MSAL) for Python -Get started with the Microsoft Authentication Library for Python to sign in users or apps with Microsoft identities ([Azure AD](https://azure.microsoft.com/services/active-directory/), [Microsoft Accounts](https://account.microsoft.com) and [Azure AD B2C](https://azure.microsoft.com/services/active-directory-b2c/) accounts) and obtain tokens to call Microsoft APIs such as [Microsoft Graph](https://graph.microsoft.io/) or your own APIs registered with the [Microsoft identity platform](https://aka.ms/aaddevv2). - -Follow steps to install the package and try out example code for basic tasks. +Get started with the Microsoft Authentication Library for Python to sign in users or apps with Microsoft identities ([Azure AD](https://azure.microsoft.com/services/active-directory/), [Microsoft Accounts](https://account.microsoft.com), and [Azure AD B2C](https://azure.microsoft.com/services/active-directory-b2c/) accounts) and obtain tokens to call Microsoft APIs such as [Microsoft Graph](https://graph.microsoft.io/) or your own APIs. ## Prerequisites -- An Azure account with an active subscription. [Create a free account][azure_sub]. +- An Azure account with an active subscription. [Create a free account](https://signup.azure.com/). - [Python 3.6+](https://www.python.org/downloads/). ## Install the package -Install the MSAL for Python package. You can find MSAL Python on [Pypi](https://pypi.org/project/msal/). +Install the MSAL for Python package. You can find MSAL Python on [PyPI](https://pypi.org/project/msal/). + ```Bash pip install msal ``` ## Setting up -Before using MSAL Python [register your application](/azure/active-directory/develop/quickstart-v2-register-an-app) with the Microsoft identity platform. +Before using MSAL Python, make sure to [register your application](/azure/active-directory/develop/quickstart-v2-register-an-app) with the Microsoft identity platform. ## Usage -Acquiring tokens with MSAL Python follows this 3-step pattern. This is the high level conceptual pattern. There will be some variations for different flows. They are demonstrated in the [runnable samples](https://github.com/AzureAD/microsoft-authentication-library-for-python/tree/dev/sample). +Acquiring tokens with MSAL Python follows a three-step pattern. There will be some variations for different flows. If you would like to see them in action, download our [samples](https://github.com/AzureAD/microsoft-authentication-library-for-python/tree/dev/sample). -1. MSAL proposes a clean separation between [public client applications, and confidential client applications](https://tools.ietf.org/html/rfc6749#section-2.1). Therefore, create either a `PublicClientApplication` or a `ConfidentialClientApplication` instance, and reuse it during the lifecycle of your app. The following example shows a `PublicClientApplication`: +1. MSAL relies on a clean separation between [public client and confidential client applications](https://tools.ietf.org/html/rfc6749#section-2.1). Therefore, create either a [`PublicClientApplication`](xref:msal.application.PublicClientApplication) or a [`ConfidentialClientApplication`](msal.application.ConfidentialClientApplication) instance and reuse it during the lifecycle of your application. For example, for a public client application, the initalization code might look like this: ```python from msal import PublicClientApplication @@ -38,12 +37,13 @@ Acquiring tokens with MSAL Python follows this 3-step pattern. This is the high authority="https://login.microsoftonline.com/Enter_the_Tenant_Name_Here") ``` - Later, each time you would want an access token, you start by: + Later, each time you would want an access token, you start by declaring a variable that will hold the token result: + ```python result = None # It is just an initial value. Please follow instructions below. ``` -2. The API model in MSAL provides you explicit control on how to utilize token cache. This cache part is technically optional, but we highly recommend you to harness the power of MSAL cache. It will automatically handle the token refresh for you. +2. The API model in MSAL provides you explicit control on how to utilize the token cache. While the caching part is technically optional, we highly recommend you to use it in your application. Using the cache you can ensure that you're not making any extra API calls and handle the token refresh automatically. ```python # We now check the cache to see @@ -60,7 +60,7 @@ Acquiring tokens with MSAL Python follows this 3-step pattern. This is the high result = app.acquire_token_silent(["your_scope"], account=chosen) ``` -3. If there is no suitable token in the cache or you've chosen to skip the previous step, send a request to Azure AD to get a token. There are different methods based on your client type and scenario. Here we demonstrate a placeholder flow. +3. If there is no suitable token in the cache or you've chosen to skip the previous step, send a request to Azure AD to get a token. There are different methods based on your client type and scenario. A sample flow can look like this: ```python if not result: @@ -74,7 +74,7 @@ Acquiring tokens with MSAL Python follows this 3-step pattern. This is the high print(result.get("correlation_id")) # You may need this when reporting a bug ``` -# Usage scenarios +## Usage scenarios MSAL Python can be used by applications to acquire tokens to access protected APIs. Tokens can be acquired by different **application types**: desktop applications, web applications, web APIs, and applications running on devices that don't have a browser (such as IoT devices). In MSAL Python, applications are categorized as follows: From 79171ca56885e6718e99e71b52446d7e7ed69e6c Mon Sep 17 00:00:00 2001 From: Den <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:31:52 -0700 Subject: [PATCH 06/10] Update index.md --- msal-python-conceptual/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msal-python-conceptual/index.md b/msal-python-conceptual/index.md index a570afd..ecb1f4e 100644 --- a/msal-python-conceptual/index.md +++ b/msal-python-conceptual/index.md @@ -81,7 +81,7 @@ MSAL Python can be used by applications to acquire tokens to access protected AP - **Public client applications (desktop and mobile)**. These types of apps cannot store app secrets securely. - **Confidential client applications (web apps, web APIs, and daemon applications)**. These type of apps securely store a secret registered with Azure AD. -Learn more about instantiating and configuring the above in the [Client applications](./client-applications.md) topic. +Learn more about instantiating and configuring the above in the [Client applications](./getting-started/client-applications.md) topic. MSAL Python supports acquiring tokens either in the name of a user or in the name of the application itself (without a user). In the latter case, a confidential client application must be used. From 8536262bc3f88cc6619f7810a8df365889994ba6 Mon Sep 17 00:00:00 2001 From: Den <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:55:00 -0700 Subject: [PATCH 07/10] Update index.md --- msal-python-conceptual/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msal-python-conceptual/index.md b/msal-python-conceptual/index.md index ecb1f4e..29244e6 100644 --- a/msal-python-conceptual/index.md +++ b/msal-python-conceptual/index.md @@ -28,7 +28,7 @@ Before using MSAL Python, make sure to [register your application](/azure/active Acquiring tokens with MSAL Python follows a three-step pattern. There will be some variations for different flows. If you would like to see them in action, download our [samples](https://github.com/AzureAD/microsoft-authentication-library-for-python/tree/dev/sample). -1. MSAL relies on a clean separation between [public client and confidential client applications](https://tools.ietf.org/html/rfc6749#section-2.1). Therefore, create either a [`PublicClientApplication`](xref:msal.application.PublicClientApplication) or a [`ConfidentialClientApplication`](msal.application.ConfidentialClientApplication) instance and reuse it during the lifecycle of your application. For example, for a public client application, the initalization code might look like this: +1. MSAL relies on a clean separation between [public client and confidential client applications](https://tools.ietf.org/html/rfc6749#section-2.1). Therefore, create either a [`PublicClientApplication`](xref:msal.application.PublicClientApplication) or a [`ConfidentialClientApplication`](xref:msal.application.ConfidentialClientApplication) instance and reuse it during the lifecycle of your application. For example, for a public client application, the initalization code might look like this: ```python from msal import PublicClientApplication From a5e3a03a52d53382276fb6820769e22d97dd453a Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:55:47 -0700 Subject: [PATCH 08/10] Update msal-python-conceptual/getting-started/acquiring-tokens.md Co-authored-by: Ray Luo --- msal-python-conceptual/getting-started/acquiring-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msal-python-conceptual/getting-started/acquiring-tokens.md b/msal-python-conceptual/getting-started/acquiring-tokens.md index 57f1225..0c8d44c 100644 --- a/msal-python-conceptual/getting-started/acquiring-tokens.md +++ b/msal-python-conceptual/getting-started/acquiring-tokens.md @@ -19,7 +19,7 @@ The approach to acquiring a token is different depending on the application type 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 [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. +- 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). - 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. From 7b1165bebc8f5491e82b9e15c642c330108ec278 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:56:02 -0700 Subject: [PATCH 09/10] Update msal-python-conceptual/getting-started/acquiring-tokens.md Co-authored-by: Ray Luo --- msal-python-conceptual/getting-started/acquiring-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msal-python-conceptual/getting-started/acquiring-tokens.md b/msal-python-conceptual/getting-started/acquiring-tokens.md index 0c8d44c..6c915af 100644 --- a/msal-python-conceptual/getting-started/acquiring-tokens.md +++ b/msal-python-conceptual/getting-started/acquiring-tokens.md @@ -27,7 +27,7 @@ Public client applications cannot securely store a secret and can _only_ authent 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 that users in batches and not one particular user, such as syncing tools. +- 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. From 4e92d11790dcf29c13e71d04b594c3898d6f9a42 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Wed, 5 Jul 2023 14:58:49 -0700 Subject: [PATCH 10/10] Update msal-python-conceptual/getting-started/acquiring-tokens.md Co-authored-by: Ray Luo --- msal-python-conceptual/getting-started/acquiring-tokens.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msal-python-conceptual/getting-started/acquiring-tokens.md b/msal-python-conceptual/getting-started/acquiring-tokens.md index 6c915af..18692d8 100644 --- a/msal-python-conceptual/getting-started/acquiring-tokens.md +++ b/msal-python-conceptual/getting-started/acquiring-tokens.md @@ -35,4 +35,4 @@ Confidential client applications can securely store a secret and can authenticat 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 use the cache, the developers will need to configure the [token cache serialization](/azure/active-directory/develop/msal-python-token-cache-serialization) logic. +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.