ClientApplication Klasse

Ihre App verfügt über eine client_id, nachdem Sie sie bei Microsoft Entra Admin Center registriert haben.

Verwenden PublicClientApplicationSie hier "Keine" .

For ConfidentialClientApplication, it supports many different input formats for different scenarios.

Unterstützung mithilfe eines geheimen Clientschlüssels. Nur Feed in einer Zeichenfolge, z "your client secret". B. .

Unterstützung für die Verwendung eines Zertifikats im X.509(PEM)-FormatDeprecated, da es SHA-1-Fingerabdruck verwendet,

es sei denn, Sie verwenden weiterhin ADFS, die nur SHA-1-Fingerabdruck unterstützt. Verwenden Sie die pfx-Option, die weiter unten auf dieser Seite dokumentiert ist. Feed in einem Diktat in diesem Formular:

   {
       "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 erfordert ein "private_key" im PEM-Format. Wenn Ihr Zertifikat im PKCS12(PFX)-Format vorliegt, können Sie es in das X.509-Format (PEM) konvertieren, nach openssl pkcs12 -in file.pfx -out file.pem -nodes. Der Fingerabdruck ist in der Registrierung Ihrer App in Azure-Portal verfügbar. Alternativ können Sie den Fingerabdruck berechnen. public_certificate (optional) ist ein Öffentliches Schlüsselzertifikat, das über den JWT-Header "x5c" gesendet wird. Dies ist nützlich, wenn Sie die Antragstellername-/Ausstellerauthentifizierung verwenden, die ein Ansatz ist, um eine einfachere Zertifikatdrehung zu ermöglichen. Pro Spezifikationen: "Das Zertifikat, das den öffentlichen Schlüssel enthält, der dem Schlüssel entspricht, der zum digitalen Signieren des JWS verwendet wird, muss das erste Zertifikat sein. Dies kann durch zusätzliche Zertifikate gefolgt werden, wobei jedes nachfolgende Zertifikat der zum Zertifizieren des vorherigen Zertifikats verwendet wird." Der Aussteller Ihres Zertifikats kann jedoch eine andere Reihenfolge verwenden. Wenn ihr Versuch also mit einem Fehler AADSTS700027 endet : "Der angegebene Signaturwert entspricht nicht dem erwarteten Signaturwert", können Sie stattdessen nur das Blattzertifikat (im PEM/str-Format) verwenden.

Unterstützung der rohen Assertion, die von einer anderen Stelle abgerufen wurde, die in Version 1.13.0 hinzugefügt wurde:

Es kann auch eine vollständig vorsignierte Assertion sein, die Sie selbst zusammengestellt haben. Übergeben Sie einfach einen Container, der nur den Schlüssel "client_assertion" enthält, wie folgt:

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

Unterstützen des Lesens von Clientzertifikaten aus PFX-DateienDiese Verwendung verwendet automatisch SHA-256-Fingerabdruck des Zertifikats. Hinzugefügt in Version 1.29.0:

Feed in ein Wörterbuch, das den Pfad zu einer PFX-Datei enthält:

   {
       "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)",
   }

Mit dem folgenden Befehl wird eine PFX-Datei aus Ihrer .key- und PEM-Datei generiert:

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

Antragstellername/Ausstellerauthentifizierung ist ein Ansatz, um eine einfachere Zertifikatdrehung zu ermöglichen. Wenn Ihre PFX-Datei sowohl den privaten Schlüssel als auch das öffentliche Zertifikat enthält, können Sie sich für die Authentifizierung des Antragstellernamens/Ausstellers anmelden, indem Sie "public_certificate" festlegen.True

In Version 0.5.0 hinzugefügt: Es handelt sich um ein Wörterbuch mit zusätzlichen Ansprüchen, die von diesem ConfidentialClientApplication privaten Schlüssel signiert werden. Sie können beispielsweise {"client_ip" verwenden: "x.x.x.x.x"}. Sie können auch einen der folgenden Standardansprüche außer Kraft setzen:

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

Eine URL, die eine Tokenautorität identifiziert. Dies sollte das Format sein. https://login.microsoftonline.com/your_tenant Standardmäßig verwenden wir https://login.microsoftonline.com/common

Geändert in Version 1.17: Sie können auch vordefinierte Konstanten und einen Generator wie folgt verwenden:

   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, ...)

(optional) Aktiviert oder deaktiviert die Autoritätsüberprüfung. Dieser Parameter ist standardmäßig auf "true" festgelegt.

Legt den tokencache fest, der von dieser ClientApplication-Instanz verwendet wird. Standardmäßig wird ein Speichercache erstellt und verwendet.

(optional) Ihre Implementierung der abstrakten Klasse HttpClient <msal.oauth2cli.http.http_client> Standard für eine Anforderungssitzungsinstanz. Da MSAL 1.11.0, wurde die Standardsitzung so konfiguriert, dass versucht wird, einen Wiederholungsfehler zu versuchen. Wenn Sie Ihre eigene http_client bereitstellen, müssen http_client Sie entscheiden, ob sie erneut versuchen möchten.

(optional) Er wird an den Verify-Parameter in der zugrunde liegenden Anforderungsbibliothek übergeben. Dies gilt nicht, wenn Sie sich entschieden haben, Ihren eigenen HTTP-Client zu übergeben.

(optional) Sie wird an den Proxyparameter in der zugrunde liegenden Anforderungsbibliothek übergeben. Dies gilt nicht, wenn Sie sich entschieden haben, Ihren eigenen HTTP-Client zu übergeben.

(optional) Sie wird an den Timeout-Parameter in der zugrunde liegenden Anforderungsbibliothek übergeben. Dies gilt nicht, wenn Sie sich entschieden haben, Ihren eigenen HTTP-Client zu übergeben.

(optional) Sie können Ihren Anwendungsnamen für Microsoft Telemetriezwecke angeben. Der Standardwert ist "None", bedeutet, dass er nicht an Microsoft übergeben wird.

(optional) Sie können Ihre Anwendungsversion für Microsoft Telemetriezwecke bereitstellen. Der Standardwert ist "None", bedeutet, dass er nicht an Microsoft übergeben wird.

(optional) Ermöglicht die Konfiguration einer oder mehrerer Clientfunktionen, z. B. ["CP1"].

Die Clientfunktion soll den Microsoft Identity Platform (STS) darüber informieren, wofür dieser Client geeignet ist, damit STS entscheiden kann, bestimmte Features zu aktivieren. Wenn der Client beispielsweise Anspruchsaufforderungen verarbeiten kann, stellt STS möglicherweise Zugriffstoken für kontinuierliche Zugriffsauswertung (Continuous Access Evaluation, CAE) auf Ressourcen aus, wobei zu wissen ist, dass der Client diese Herausforderungen bewältigen kann, wenn die Ressource eine Anspruchsaufforderung ausgibt.

Implementierungsdetails: Die Clientfunktion wird zur zeit mithilfe des Parameters "Claims" im Draht implementiert. MSAL kombiniert sie in einem Anspruchsparameter , den Sie später über eine der Abrufen-Token-Anforderung bereitstellen.

(optional) Weist MSAL an, den regionalen Entra-Tokendienst zu verwenden. Dieses Legacyfeature ist nur für Erstanbieteranwendungen verfügbar. Nur acquire_token_for_client() wird unterstützt.

Unterstützt vier Werte:

1. azure_region=None - Dieser Standardwert bedeutet, dass keine Region konfiguriert ist. MSAL verwendet die region, die in env var MSAL_FORCE_REGIONdefiniert ist.

2. azure_region="some_region" - bedeutet, dass die angegebene Region verwendet wird.

3. azure_region=True - das bedeutet, dass MSAL versucht, die Region automatisch zu erkennen. Dies wird nicht empfohlen.

4. azure_region=False - das bedeutet, dass MSAL keine Region verwendet.

Neu in Version 1.12.0.

(optional) In der Vergangenheit hardcodes MSAL offline_access Bereich, wodurch Ihre App längeren Zugriff auf die Daten des Benutzers haben würde. Wenn dies für Ihre App unnötig oder nicht erwünscht ist, können Sie diesen Parameter jetzt verwenden, um eine Ausschlussliste mit Bereichen wie z exclude_scopes = ["offline_access"]. B. .

MSAL ist seit langem Zwischenspeicherungstoken in der token_cache. In letzter Zeit führte MSAL auch ein Konzept von http_cache, durch automatisches Zwischenspeichern einiger begrenzter Mengen von nicht tokenfreien HTTP-Antworten, so dass langelebigPublicClientApplication und ConfidentialClientApplication leistungsfähiger und reaktionsfähiger in einigen Situationen wäre.

Dieser http_cache Parameter akzeptiert ein beliebiges dict-like-Objekt. Wenn nicht angegeben, verwendet MSAL ein In-Memory-Diktat.

Wenn Es sich bei Ihrer App um eine Befehlszeilen-App (CLI) handelt, sollten Sie Ihre http_cache über unterschiedliche CLI-Ausführung hinweg beibehalten. Das Format der permanenten Datei kann sich aufgrund des instabilen Protokolls ändern, sodass ihre Implementierung unerwartete Ladefehler tolerieren muss. Das folgende Rezept zeigt eine Möglichkeit, dies zu tun:

   # 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"], ...)

Inhalt innerhalb http_cache sind billig zu erhalten. Es ist nicht erforderlich, sie für verschiedene Apps freizugeben.

Inhalte innerhalb http_cache enthalten keine Token oder personenbezogene Informationen (Personally Identifiable Information, PII). Verschlüsselung ist unnötig.

Neu in Version 1.16.0.

In der Vergangenheit würde MSAL eine Verbindung mit einem zentralen Endpunkt herstellen, der sich befindet https://login.microsoftonline.com , um einige Metadaten zu erhalten, insbesondere bei Verwendung einer unbekannten Autorität. Dieses Verhalten wird als Instance Discovery bezeichnet.

Dieser Parameter ist standardmäßig "None", wodurch die Instanzermittlung aktiviert wird.

Wenn Sie einige Behörden kennen, mit denen MsAL mit as-isarbeiten kann, ohne Instance Discovery einzubeziehen, ist das empfohlene Muster:

   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,
       )

Wenn Sie einige Behörden vorher noch nicht kennen, möchten Sie dennoch, dass MSAL alle von Ihnen bereitgestellten Autoritäten akzeptiert, können Sie die False Instanzermittlung bedingungslos deaktivieren.

Neu in Version 1.19.0.

Deprecated. Verwenden Sie stattdessen enable_broker_on_windows.

Wenn diese Option aktiviert ist, können Protokolle PII (personenbezogene Informationen) enthalten. Dies kann bei der Problembehandlung bei Brokerverhalten hilfreich sein. Das Standardverhalten lautet "False".

Neu in Version 1.24.0.

In Version 1.28.0 hinzugefügt: Es handelt sich um eine URL, die eine OpenID Connect (OIDC)-Autorität des Formats https://contoso.com/tenantidentifiziert. MSAL fügt ".well-known/openid-configuration" an die Autorität an und ruft die OIDC-Metadaten von dort ab, um die Endpunkte zu ermitteln.

Hinweis: Der Broker wird NICHT für die OIDC-Autorität verwendet.