PublicClientApplication Classe

Identique à <xref:ClientApplication.__init__>, sauf que ce client_credential paramètre doit rester None.

Note

Qu’est-ce qu’un répartiteur et pourquoi l’utiliser ?

Un répartiteur est un composant installé sur votre appareil.

Broker donne implicitement à votre appareil une identité. En utilisant un répartiteur,

votre appareil devient un facteur capable de satisfaire l’authentification multifacteur (multifacteur).

Ce facteur serait devenu obligatoire

si l’administrateur d’un locataire active une stratégie d’accès conditionnel (CA) correspondante.

La présence du répartiteur autorise Plateforme d'identités Microsoft

pour avoir une plus grande confiance que les jetons sont émis sur votre appareil,

et c’est plus sûr.

Un avantage supplémentaire du répartiteur est,

il s’exécute en tant que processus de longue durée avec le système d’exploitation de votre appareil,

et gère son propre cache,

afin que vos applications avec répartiteur (même une interface CLI)

peut automatiquement l’authentification unique à partir d’une session de connexion établie précédemment.

Comment choisir d’utiliser le répartiteur ?

Vous pouvez définir n’importe quelle combinaison des paramètres d’opt-in suivants sur true :

Indicateur d’inscription

Si l’application s’exécute sur

L’application a inscrit ceci en tant qu’URI de redirection de plateforme de bureau dans Portail Azure

enable_broker_on_windows

Windows 10+

ms-appx-web ://Microsoft. AAD. BrokerPlugin/your_client_id

enable_broker_on_wsl

WSL

ms-appx-web ://Microsoft. AAD. BrokerPlugin/your_client_id

enable_broker_on_mac

Mac avec Portail d'entreprise installé

msauth.com.msauth.unsignedapp ://auth

enable_broker_on_linux

Linux avec Intune installé

https://login.microsoftonline.com/common/oauth2/nativeclient (DOIT être activé)

Installer la dépendance broker,

par exemple, pip install msal[broker]>=1.33,2<.

Testez avec acquire_token_interactive() et acquire_token_silent().

Les comportements de secours de la prise en charge du répartiteur de MSAL Python

MSAL va effectuer une erreur ou revenir en mode silencieux aux flux non répartiteurs.

MSAL ignore le enable_broker_... et contourner le répartiteur

sur ces flux d’authentification connus pour ne pas être pris en charge par le répartiteur.

Cela inclut ADFS, B2C, etc..

Pour d’autres scénarios « could-use-broker », consultez ci-dessous.

Erreurs MSAL lorsque le développeur d’applications a choisi d’utiliser le répartiteur

mais un package de dépendance directe « intermédiaire » n’est pas installé.

Le message d’erreur guide le développeur d’applications pour déclarer la dépendance correcte

msal[broker].

Nous avons une erreur ici, car l’erreur est exploitable pour les développeurs d’applications.

MSAL « désactive » silencieusement le répartiteur et la secours vers un autre répartiteur,

lorsqu’elle est activée, la dépendance installée n’a pas pu être initialisé.

Nous prévoyons que cela se produise sur un appareil dont le système d’exploitation est trop ancien

ou le composant broker sous-jacent n’est pas disponible en quelque sorte.

Il n’y a pas beaucoup de développeurs d’applications ou l’utilisateur final peut faire ici.

Finalement, la stratégie d’accès conditionnel doit

forcer l’utilisateur à basculer vers un autre appareil.

Erreurs MSAL lorsque le répartiteur est choisi, installé, initialisé,

mais les demandes de jeton suivantes ont échoué.

Constructeur

PublicClientApplication(client_id, client_credential=None, *, enable_broker_on_windows=None, enable_broker_on_mac=None, enable_broker_on_linux=None, enable_broker_on_wsl=None, **kwargs)

Paramètres

Nom Description
enable_broker_on_windows
Obligatoire
<xref:boolean>

Ce paramètre n’est effectif que si votre application s’exécute sur Windows 10+. Ce paramètre est défini par défaut sur None, ce qui signifie que MSAL n’utilise pas de répartiteur.

Nouveautés de MSAL Python 1.25.0.
enable_broker_on_mac
Obligatoire
<xref:boolean>

Ce paramètre n’est effectif que si votre application s’exécute sur Mac. Ce paramètre est défini par défaut sur None, ce qui signifie que MSAL n’utilise pas de répartiteur.

Nouveautés de MSAL Python 1.31.0.
enable_broker_on_linux
Obligatoire
<xref:boolean>

Ce paramètre est effectif uniquement si votre application s’exécute sur Linux, y compris WSL. Ce paramètre est défini par défaut sur None, ce qui signifie que MSAL n’utilise pas de répartiteur.

Nouveautés de MSAL Python 1.33.0.
enable_broker_on_wsl
Obligatoire
<xref:boolean>

Ce paramètre est effectif uniquement si votre application s’exécute sur WSL. Ce paramètre est défini par défaut sur None, ce qui signifie que MSAL n’utilise pas de répartiteur.

Nouveautés de MSAL Python 1.33.0.
client_id
Obligatoire
client_credential
Valeur par défaut: None

Paramètres de mot clé uniquement

Nom Description
enable_broker_on_windows
Valeur par défaut: None
enable_broker_on_mac
Valeur par défaut: None
enable_broker_on_linux
Valeur par défaut: None
enable_broker_on_wsl
Valeur par défaut: None

Méthodes

acquire_token_by_device_flow

Obtenez un jeton par un objet de flux d’appareil, avec un effet d’interrogation personnalisable.
acquire_token_interactive

Acquérir un jeton de manière interactive, c’est-à-dire via un navigateur local.

Prérequis : Dans Portail Azure, configurez l’URI de redirection de votre « application mobile et de bureau » en tant que http://localhost. Si vous choisissez d’utiliser le répartiteur lors PublicClientApplication de la création, votre application a également besoin de cet URI de redirection : ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID
initiate_device_flow

Lancez une instance device Flow, qui sera utilisée dans acquire_token_by_device_flow.

acquire_token_by_device_flow

Obtenez un jeton par un objet de flux d’appareil, avec un effet d’interrogation personnalisable.

acquire_token_by_device_flow(flow, claims_challenge=None, **kwargs)

Paramètres

Nom Description
flow
Obligatoire
dict

dictée précédemment générée par initiate_device_flow. Par défaut, l’effet d’interrogation de cette méthode bloque le thread actuel. Vous pouvez abandonner la boucle d’interrogation à tout moment, en modifiant la valeur de la clé « expires_at » du flux sur 0.
claims_challenge

Le paramètre claims_challenge demande des revendications spécifiques demandées par le fournisseur de ressources sous la forme d’une directive claims_challenge dans l’en-tête www-authenticate à retourner à partir du point de terminaison UserInfo et/ou dans le jeton d’ID et/ou le jeton d’accès. Il s’agit d’une chaîne d’un objet JSON qui contient des listes de revendications demandées à partir de ces emplacements.

Valeur par défaut: None

Retours

Type Description

dictée représentant la réponse json de Microsoft Entra :

  • Une réponse réussie contient la clé « access_token »,

  • une réponse d’erreur contient « error » et généralement « error_description ».

acquire_token_interactive

Acquérir un jeton de manière interactive, c’est-à-dire via un navigateur local.

Prérequis : Dans Portail Azure, configurez l’URI de redirection de votre « application mobile et de bureau » en tant que http://localhost. Si vous choisissez d’utiliser le répartiteur lors PublicClientApplication de la création, votre application a également besoin de cet URI de redirection : ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID

acquire_token_interactive(scopes, prompt=None, login_hint=None, domain_hint=None, claims_challenge=None, timeout=None, port=None, extra_scopes_to_consent=None, max_age=None, parent_window_handle=None, on_before_launching_ui=None, auth_scheme=None, **kwargs)

Paramètres

Nom Description
scopes
Obligatoire
list

Il s’agit d’une liste de chaînes sensibles à la casse.
prompt
str

Par défaut, aucune valeur d’invite n’est envoyée, pas même chaîne "none". Vous devrez spécifier explicitement une valeur. Ses valeurs valides sont les constantes définies dans <xref:msal.Prompt>.

Valeur par défaut: None
login_hint
str

Optional. Identificateur de l'utilisateur. En règle générale, un nom d’utilisateur principal (UPN).

Valeur par défaut: None
domain_hint

Il peut s’agir d’un « consommateur » ou d’une « organisation » ou d’un domaine de locataire « contoso.com ». S’il est inclus, il ignore le processus de découverte par e-mail que l’utilisateur passe sur la page de connexion, ce qui entraîne une expérience utilisateur légèrement plus simplifiée. Pour plus d’informations sur les valeurs possibles disponibles dans le document Flux de code d’authentification et domain_hint document.

Valeur par défaut: None
claims_challenge

Le paramètre claims_challenge demande des revendications spécifiques demandées par le fournisseur de ressources sous la forme d’une directive claims_challenge dans l’en-tête www-authenticate à retourner à partir du point de terminaison UserInfo et/ou dans le jeton d’ID et/ou le jeton d’accès. Il s’agit d’une chaîne d’un objet JSON qui contient des listes de revendications demandées à partir de ces emplacements.

Valeur par défaut: None
timeout
int

Cette méthode bloque le thread actuel. Ce paramètre spécifie la valeur de délai d’expiration en secondes. La valeur None par défaut signifie attendre indéfiniment.

Valeur par défaut: None
port
int

Port à utiliser pour écouter une réponse d’authentification entrante. Par défaut, nous allons utiliser un port alloué par le système. (Le reste de la redirect_uri est codée en dur en tant que http://localhost.)

Valeur par défaut: None
extra_scopes_to_consent
list

« Les étendues supplémentaires au consentement » sont un concept disponible uniquement dans Microsoft Entra. Il fait référence à d’autres ressources que vous voudrez peut-être inviter à donner son consentement, dans la même interaction, mais pour laquelle vous ne récupérerez pas de jeton pour cette opération particulière.

Valeur par défaut: None
max_age
int

FACULTATIF. Âge maximal de l’authentification. Spécifie le temps écoulé autorisé en secondes depuis la dernière fois que le End-User a été authentifié activement. Si le temps écoulé est supérieur à cette valeur, Plateforme d'identités Microsoft authentifie activement l’utilisateur final.

MSAL Python valide également automatiquement la auth_time dans le jeton d’ID.

Nouveautés de la version 1.15.

Valeur par défaut: None
parent_window_handle
int

FACULTATIF.

  • Si votre application n’opte pas pour utiliser le répartiteur, vous n’avez pas besoin de fournir ici.parent_window_handle

  • Si votre application choisit d’utiliser le répartiteur, parent_window_handle elle est requise.

    • Si votre application est une application GUI s’exécutant sur Windows ou le système Mac, vous devez également fournir sa poignée de fenêtre, afin que la fenêtre de connexion s’affiche en haut de votre fenêtre.

    • Si votre application est une application console s’exécutant sur Windows ou le système Mac, vous pouvez utiliser un espace réservéPublicClientApplication.CONSOLE_WINDOW_HANDLE.

La plupart des scripts Python sont des applications console.

Nouveautés de la version 1.20.0.

Valeur par défaut: None
on_before_launching_ui
<xref:function>

Rappel avec la forme de lambda ui="xyz", **kwargs: print("A {} will be launched".format(ui)), où ui sera « navigateur » ou « broker ». Vous pouvez l’utiliser pour informer votre utilisateur final de s’attendre à une fenêtre contextuelle.

Nouveautés de la version 1.20.0.

Valeur par défaut: None
auth_scheme
object

Vous pouvez fournir un msal.auth_scheme.PopAuthScheme objet afin que MSAL obtienne un jeton POP (Proof-of-Possession) pour vous.

Nouveautés de la version 1.26.0.

Valeur par défaut: None

Retours

Type Description

  • Une dictée ne contenant aucune clé « erreur », et contient généralement une clé « access_token ».

  • Dict contenant une clé « erreur », lorsque l’actualisation du jeton a échoué.

initiate_device_flow

Lancez une instance device Flow, qui sera utilisée dans acquire_token_by_device_flow.

initiate_device_flow(scopes=None, *, claims_challenge=None, **kwargs)

Paramètres

Nom Description
scopes
list[str]

Étendues demandées pour accéder à une API protégée (une ressource).

Valeur par défaut: None

Paramètres de mot clé uniquement

Nom Description
claims_challenge
Valeur par défaut: None

Retours

Type Description

dictée représentant un objet Device Flow nouvellement créé.

  • Une réponse réussie contient la clé « user_code », entre autres

  • une réponse d’erreur contient d’autres paires clé/valeur lisibles.

Attributs

CONSOLE_WINDOW_HANDLE 

CONSOLE_WINDOW_HANDLE = <object object>

DEVICE_FLOW_CORRELATION_ID 

DEVICE_FLOW_CORRELATION_ID = '_correlation_id'