ClientApplication Classe

Votre application a un client_id après l’avoir inscrite sur centre d’administration Microsoft Entra.

Pour PublicClientApplication, vous utilisez Aucun ici.

Pour ConfidentialClientApplication, il prend en charge de nombreux formats d’entrée différents pour différents scénarios.

Prise en charge à l’aide d’une clé secrète client. Il vous suffit de nourrir dans une chaîne, telle que "your client secret".

Prise en charge de l’utilisation d’un certificat au format X.509 (.pem)Deprecated car il utilise l’empreinte SHA-1,

sauf si vous utilisez toujours ADFS qui prend uniquement en charge l’empreinte numérique SHA-1. Utilisez l’option .pfx documentée plus loin dans cette page. Feed in a dict in this form :

   {
       "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format",
       "thumbprint": "An SHA-1 thumbprint such as A1B2C3D4E5F6..."
           "Changed in version 1.35.0, if thumbprint is absent"
           "and a public_certificate is present, MSAL will"
           "automatically calculate an SHA-256 thumbprint instead.",
       "passphrase": "Needed if the private_key is encrypted (Added in version 1.6.0)",
       "public_certificate": "...-----BEGIN CERTIFICATE-----...",  # Needed if you use Subject Name/Issuer auth. Added in version 0.5.0.
   }

MSAL Python nécessite un « private_key » au format PEM. Si votre certificat est au format PKCS12 (.pfx), vous pouvez le convertir au format X.509 (.pem), par openssl pkcs12 -in file.pfx -out file.pem -nodes. L'empreinte numérique est disponible dans l'inscription de votre application dans Portail Azure. Vous pouvez également calculer l’empreinte numérique. public_certificate (facultatif) est un certificat de clé publique qui sera envoyé via l’en-tête JWT « x5c ». Cela est utile lorsque vous utilisez l’authentification du nom/de l’émetteur de l’objet , qui est une approche pour faciliter la rotation des certificats. Selon les spécifications, « le certificat contenant la clé publique correspondant à la clé utilisée pour signer numériquement le JWS doit être le premier certificat. Cela PEUT être suivi de certificats supplémentaires, chaque certificat suivant étant celui utilisé pour certifier le certificat précédent. Toutefois, l’émetteur de votre certificat peut utiliser un ordre différent. Par conséquent, si votre tentative se termine par une erreur AADSTS700027 : « La valeur de signature fournie ne correspond pas à la valeur de signature attendue », vous pouvez essayer d’utiliser uniquement le certificat feuille (au format PEM/str) à la place.

Prise en charge de l’assertion brute obtenue à partir d’un autre emplacementajouté dans la version 1.13.0 :

Il peut également s’agir d’une assertion complètement pré-signée que vous avez assemblée vous-même. Transmettez simplement un conteneur contenant uniquement la clé « client_assertion », comme suit :

   {
       "client_assertion": "...a JWT with claims aud, exp, iss, jti, nbf, and sub..."
   }

La prise en charge de la lecture des certificats clients à partir de fichiers PFX Cette utilisation utilise automatiquement l’empreinte SHA-256 du certificat. Ajouté dans la version 1.29.0 :

Flux dans un dictionnaire contenant le chemin d’accès à un fichier PFX :

   {
       "private_key_pfx_path": "/path/to/your.pfx",  # Added in version 1.29.0
       "public_certificate": True,  # Only needed if you use Subject Name/Issuer auth. Added in version 1.30.0
       "passphrase": "Passphrase if the private_key is encrypted (Optional)",
   }

La commande suivante génère un fichier .pfx à partir de votre fichier .key et .pem :

   openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.pem

L’authentification de l’émetteur/nom de l’objet est une approche permettant de faciliter la rotation des certificats. Si votre fichier .pfx contient à la fois la clé privée et le certificat public, vous pouvez opter pour l’authentification de l’objet/émetteur en définissant « public_certificate » sur True.

Ajouté dans la version 0.5.0 : il s’agit d’un dictionnaire de revendications supplémentaires qui seraient signées par cette ConfidentialClientApplication clé privée. Par exemple, vous pouvez utiliser {"client_ip » : « x.x.x.x"}. Vous pouvez également remplacer l’une des revendications par défaut suivantes :

   {
       "aud": the_token_endpoint,
       "iss": self.client_id,
       "sub": same_as_issuer,
       "exp": now + 10_min,
       "iat": now,
       "jti": a_random_uuid
   }

URL qui identifie une autorité de jeton. Il doit s’agir du format https://login.microsoftonline.com/your_tenant Par défaut, nous allons utiliser https://login.microsoftonline.com/common

Modifié dans la version 1.17 : vous pouvez également utiliser une constante prédéfinie et un générateur comme suit :

   from msal.authority import (
       AuthorityBuilder,
       AZURE_US_GOVERNMENT, AZURE_CHINA, AZURE_PUBLIC)
   my_authority = AuthorityBuilder(AZURE_PUBLIC, "contoso.onmicrosoft.com")
   # Now you get an equivalent of
   # "https://login.microsoftonline.com/contoso.onmicrosoft.com"

   # You can feed such an authority to msal's ClientApplication
   from msal import PublicClientApplication
   app = PublicClientApplication("my_client_id", authority=my_authority, ...)

(facultatif) Active ou désactive la validation de l’autorité. Ce paramètre a la valeur true par défaut.

Définit le cache de jeton utilisé par cette instance ClientApplication. Par défaut, un cache en mémoire est créé et utilisé.

(facultatif) Votre implémentation de la classe abstraite HttpClient <msal.oauth2cli.http.http_client> Valeurs par défaut pour une instance de session de requêtes. Étant donné que MSAL 1.11.0, la session par défaut est configurée pour tenter une nouvelle tentative lors de l’erreur de connexion. Si vous fournissez votre propre http_client, il s’agit du devoir de votre http_client de décider s’il faut effectuer une nouvelle tentative.

(facultatif) Il sera transmis au paramètre de vérification dans la bibliothèque de demandes sous-jacentes . Cela ne s’applique pas si vous avez choisi de passer votre propre client Http

(facultatif) Elle sera transmise au paramètre proxy dans la bibliothèque de demandes sous-jacentes . Cela ne s’applique pas si vous avez choisi de passer votre propre client Http

(facultatif) Il sera passé au paramètre de délai d’expiration dans la bibliothèque de demandes sous-jacentes Ceci ne s’applique pas si vous avez choisi de passer votre propre client Http

(facultatif) Vous pouvez fournir le nom de votre application à des fins de télémétrie Microsoft. La valeur par défaut est None, ce qui signifie qu’elle n’est pas transmise à Microsoft.

(facultatif) Vous pouvez fournir la version de votre application à des fins de télémétrie Microsoft. La valeur par défaut est None, ce qui signifie qu’elle n’est pas transmise à Microsoft.

(facultatif) Autorise la configuration d’une ou plusieurs fonctionnalités clientes, par exemple ["CP1"].

La fonctionnalité cliente est destinée à informer le Plateforme d'identités Microsoft (STS) de ce que ce client est capable, afin que STS puisse décider d’activer certaines fonctionnalités. Par exemple, si le client est capable de gérer la demande de revendications, STS peut émettre des jetons d’accès d’évaluation continue d’accès (CAE) aux ressources, sachant que lorsque la ressource émet un défi de revendications , le client pourra gérer ces défis.

Détails de l’implémentation : la fonctionnalité cliente est implémentée à l’aide du paramètre « claims » sur le câble, pour le moment. MSAL les combine en paramètre de revendications que vous fournirez ultérieurement via l’une des demandes d’acquisition de jeton.

(facultatif) Indique à MSAL d’utiliser le service de jeton régional Entra. Cette fonctionnalité héritée est disponible uniquement pour les applications internes. Seul acquire_token_for_client() est pris en charge.

Prend en charge 4 valeurs :

1. azure_region=None - Cette valeur par défaut signifie qu’aucune région n’est configurée. MSAL utilise la région définie dans env var MSAL_FORCE_REGION.

2. azure_region="some_region" : signifie que la région spécifiée est utilisée.

3. azure_region=True : signifie que MSAL tente de détecter automatiquement la région. Cela n’est pas recommandé.

4. azure_region=False : signifie que MSAL n’utilise aucune région.

Nouveautés de la version 1.12.0.

(facultatif) Les codes durs MSAL historiquement offline_access étendue, ce qui permettrait à votre application d’avoir un accès prolongé aux données de l’utilisateur. Si cela n’est pas nécessaire ou indésirable pour votre application, vous pouvez maintenant utiliser ce paramètre pour fournir une liste d’exclusions d’étendues, par exclude_scopes = ["offline_access"]exemple .

MSAL a longtemps mis en cache des jetons dans le token_cache. Récemment, MSAL a également introduit un concept de http_cache, en mettant automatiquement en cache une quantité finie de réponses http non-jetons, de sorte que les réponses http de longue duréePublicClientApplication et seraient plus performantes et ConfidentialClientApplication réactives dans certaines situations.

Ce http_cache paramètre accepte n’importe quel objet de type dicté. S’il n’est pas fourni, MSAL utilise une dictée en mémoire.

Si votre application est une application en ligne de commande (CLI), vous souhaitez conserver votre http_cache entre différentes exécutions CLI. Le format du fichier persistant peut changer en raison, mais pas limité au protocole instable, de sorte que votre implémentation tolérera des erreurs de chargement inattendues. La recette suivante montre un moyen de le faire :

   # Just add the following lines at the beginning of your CLI script
   import sys, atexit, pickle, logging
   http_cache_filename = sys.argv[0] + ".http_cache"
   try:
       with open(http_cache_filename, "rb") as f:
           persisted_http_cache = pickle.load(f)  # Take a snapshot
   except (
           FileNotFoundError,  # Or IOError in Python 2
           pickle.UnpicklingError,  # A corrupted http cache file
           AttributeError,  # Cache created by a different version of MSAL
           ):
       persisted_http_cache = {}  # Recover by starting afresh
   except:  # Unexpected exceptions
       logging.exception("You may want to debug this")
       persisted_http_cache = {}  # Recover by starting afresh
   atexit.register(lambda: pickle.dump(
       # When exit, flush it back to the file.
       # It may occasionally overwrite another process's concurrent write,
       # but that is fine. Subsequent runs will reach eventual consistency.
       persisted_http_cache, open(http_cache_file, "wb")))

   # And then you can implement your app as you normally would
   app = msal.PublicClientApplication(
       "your_client_id",
       ...,
       http_cache=persisted_http_cache,  # Utilize persisted_http_cache
       ...,
       #token_cache=...,  # You may combine the old token_cache trick
           # Please refer to token_cache recipe at
           # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
       )
   app.acquire_token_interactive(["your", "scope"], ...)

Le contenu à l’intérieur http_cache est bon marché pour obtenir. Il n’est pas nécessaire de les partager entre différentes applications.

Le contenu à l’intérieur http_cache ne contiendra pas de jetons ni d’informations d’identification personnelle (PII). Le chiffrement n’est pas nécessaire.

Nouveautés de la version 1.16.0.

Historiquement, MSAL se connecterait à un point de terminaison central situé à https://login.microsoftonline.com l’acquisition de certaines métadonnées, en particulier lorsque vous utilisez une autorité inconnue. Ce comportement est appelé Découverte d’instances.

Ce paramètre est défini par défaut sur None, ce qui active la découverte d’instances.

Si vous connaissez certaines autorités que vous autorisez MSAL à utiliser avec as-is, sans impliquer de découverte d’instance, le modèle recommandé est :

   known_authorities = frozenset([  # Treat your known authorities as const
       "https://contoso.com/adfs", "https://login.azs/foo"])
   ...
   authority = "https://contoso.com/adfs"  # Assuming your app will use this
   app1 = PublicClientApplication(
       "client_id",
       authority=authority,
       # Conditionally disable Instance Discovery for known authorities
       instance_discovery=authority not in known_authorities,
       )

Si vous ne connaissez pas certaines autorités au préalable, mais souhaitez toujours que MSAL accepte toute autorité que vous fournirez, vous pouvez utiliser un False pour désactiver inconditionnellement la découverte d’instances.

Nouveautés de la version 1.19.0.

Déconseillé. Utilisez plutôt enable_broker_on_windows.

Lorsqu’ils sont activés, les journaux d’activité peuvent inclure des informations d’identification personnelles (informations d’identification personnelles). Cela peut être utile pour résoudre les problèmes de comportement des répartiteurs. Le comportement par défaut est False.

Nouveautés de la version 1.24.0.

Ajouté dans la version 1.28.0 : il s’agit d’une URL qui identifie une autorité OpenID Connect (OIDC) du format https://contoso.com/tenant. MSAL ajoute .well-known/openid-configuration » à l’autorité et récupère les métadonnées OIDC à partir de là pour déterminer les points de terminaison.

Remarque : Le répartiteur ne sera pas utilisé pour l’autorité OIDC.