From d392c5282a169ffae498eb10eabaf92ab48c5afb Mon Sep 17 00:00:00 2001 From: Sherman Ouko <12745944+SHERMANOUKO@users.noreply.github.com> Date: Thu, 7 Mar 2024 13:55:21 +0300 Subject: [PATCH 1/2] Improve client app documentation --- .../getting-started/client-applications.md | 49 +++++++++++++------ 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/msal-python-conceptual/getting-started/client-applications.md b/msal-python-conceptual/getting-started/client-applications.md index f6062a5..b981788 100644 --- a/msal-python-conceptual/getting-started/client-applications.md +++ b/msal-python-conceptual/getting-started/client-applications.md @@ -1,52 +1,69 @@ --- title: Client applications description: "How to instantiate client applications in MSAL Python." -author: Dickson-Mwendia +author: SHERMANOUKO manager: CelesteDG ms.service: msal ms.subservice: msal-python ms.topic: conceptual -ms.date: 02/07/2024 -ms.author: dmwendia -ms.reviewer: shermanouko, rayluo +ms.date: 03/07/2024 +ms.author: shermanouko +ms.reviewer: dmwendia, rayluo --- # Client applications -## Instantiating an application +Microsoft Authentication Library (MSAL) Python supports two types of client applications: public client applications and confidential client applications. The client types are distinguished by their ability to authenticate securely with the authorization server and to hold sensitive, identity proving information so that it can't be accessed or known to a user within the scope of its access. This article focuses on how to initialize these applications using MSAL Python. -### Prerequisites +## Prerequisites -Before instantiating your app with MSAL Python: +This article doesn't go deep into defining what a public and confidential client applications are. Visit the identity platform docs to learn more about [public and confidential client applications](/entra/identity-platform/msal-client-applications). -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 Microsoft Entra ID. 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 Microsoft Entra ID will use to return the code. For desktop applications you will need to add `http://localhost` if you're not relying on authentication brokers. +## Instantiate an application -### Instantiating a public client application +You require an app registration to initiate an app. [Register an app](/entra/identity-platform/quickstart-register-app) in the Microsoft Entra admin center. From the registration page, you need: + +- The application client identifieR. This is 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're writing a line of business application scoped to just your organization (also known as a single-tenant application). +- If you're building a confidential client app, create an application secret in the form of a string or certificate. +- For web applications, set the redirect URL that Microsoft Entra ID uses to return the code. For desktop applications, add `http://localhost` if you're not relying on authentication brokers. + +## Instantiate a public client application Public client applications use the [`PublicClientApplication`](xref:msal.application.PublicClientApplication) class. ```python +import msal + app = msal.PublicClientApplication( "client_id", authority="authority", ) ``` -### Instantiating a confidential client application +## Instantiate a confidential client application Confidential client applications use the [`ConfidentialClientApplication`](xref:msal.application.ConfidentialClientApplication) class. ```python +import msal + app = msal.ConfidentialClientApplication( "client_id", authority="authority", client_credential="client_secret", ) ``` + +## Caching + +When you instantiate a client application, there are two parameters you can use to define your caching preferences. These parameters are: `token_cache` and `http_cache`. + +- `token_cache` sets the token cache used by the client application instance. By default, an in-memory cache is created and used. For more information, see [token caching in MSAL Python](msal-python-token-cache-serialization.md). +- `http_cache` is available in MSAL Python version 1.16+. This automatically caches some finite number of nontoken http responses, so that long-lived `PublicClientApplication` and `ConfidentialClientApplication` instances would be more performant and responsive in some situations. If the `http_cache` parameter isn't provided, MSAL uses an in-memory dict. If your app is a command-line app (CLI), you would want to persist your `http_cache` across different CLI runs. For more information, see the [reference guide](/python/api/msal/msal.application.clientapplication). + +## Next steps + +[Acquire tokens for your app](acquiring-tokens.md). From 4e941b58699c2c0494b83c7c46a3f80acca6d8fa Mon Sep 17 00:00:00 2001 From: Sherman Ouko <12745944+SHERMANOUKO@users.noreply.github.com> Date: Thu, 7 Mar 2024 15:26:52 +0300 Subject: [PATCH 2/2] Improve client app documentation --- msal-python-conceptual/getting-started/client-applications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msal-python-conceptual/getting-started/client-applications.md b/msal-python-conceptual/getting-started/client-applications.md index b981788..9f4aa27 100644 --- a/msal-python-conceptual/getting-started/client-applications.md +++ b/msal-python-conceptual/getting-started/client-applications.md @@ -61,7 +61,7 @@ app = msal.ConfidentialClientApplication( When you instantiate a client application, there are two parameters you can use to define your caching preferences. These parameters are: `token_cache` and `http_cache`. -- `token_cache` sets the token cache used by the client application instance. By default, an in-memory cache is created and used. For more information, see [token caching in MSAL Python](msal-python-token-cache-serialization.md). +- `token_cache` sets the token cache used by the client application instance. By default, an in-memory cache is created and used. For more information, see [token caching in MSAL Python](../advanced/msal-python-token-cache-serialization.md). - `http_cache` is available in MSAL Python version 1.16+. This automatically caches some finite number of nontoken http responses, so that long-lived `PublicClientApplication` and `ConfidentialClientApplication` instances would be more performant and responsive in some situations. If the `http_cache` parameter isn't provided, MSAL uses an in-memory dict. If your app is a command-line app (CLI), you would want to persist your `http_cache` across different CLI runs. For more information, see the [reference guide](/python/api/msal/msal.application.clientapplication). ## Next steps