ClientApplication Klas

Uw app heeft een client_id nadat u deze hebt geregistreerd op Microsoft Entra-beheercentrum.

Voor PublicClientApplication, gebruik je Geen hier.

Hiervoor ConfidentialClientApplicationondersteunt het veel verschillende invoerindelingen voor verschillende scenario's.

Ondersteuning met behulp van een clientgeheim. Voer gewoon een tekenreeks in, zoals "your client secret".

Ondersteuning voor het gebruik van een certificaat in X.509-indeling (.pem) afgeschaft omdat deze GEBRUIKMAAKT van SHA-1-vingerafdruk,

tenzij u nog steeds ADFS gebruikt die alleen SHA-1-vingerafdruk ondersteunt. Gebruik de pfx-optie die verderop op deze pagina wordt beschreven. Feed in een dict in deze vorm:

   {
       "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 vereist een 'private_key' in PEM-indeling. Als uw certificaat de PKCS12-indeling (.pfx) heeft, kunt u het converteren naar X.509-indeling (.pem), op openssl pkcs12 -in file.pfx -out file.pem -nodes. De vingerafdruk is beschikbaar in de registratie van uw app in Azure Portal. U kunt ook de vingerafdruk berekenen. public_certificate (optioneel) is een openbaar sleutelcertificaat dat wordt verzonden via de JWT-header 'x5c'. Dit is handig wanneer u verificatie voor onderwerpnaam/verlener gebruikt. Dit is een methode om het rouleren van certificaten te vereenvoudigen. Per specificaties: "het certificaat met de openbare sleutel dat overeenkomt met de sleutel die wordt gebruikt om de JWS digitaal te ondertekenen, moet het eerste certificaat zijn. Dit kan worden gevolgd door extra certificaten, waarbij elk volgend certificaat het certificaat is dat wordt gebruikt om het vorige certificaat te certificeren." De verlener van uw certificaat kan echter een andere volgorde gebruiken. Als uw poging eindigt op een fout AADSTS700027 : 'De opgegeven handtekeningwaarde komt niet overeen met de verwachte handtekeningwaarde', kunt u in plaats daarvan alleen het bladcertificaat (in PEM/str-indeling) gebruiken.

Ondersteunende onbewerkte assertie die afkomstig is van elderstoegevoegd in versie 1.13.0:

Het kan ook een volledig vooraf ondertekende verklaring zijn die u zelf hebt samengesteld. Geef gewoon een container door die alleen de sleutel 'client_assertion' bevat, zoals hieronder:

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

Ondersteuning voor het lezen van clientcertificaten uit PFX-bestanden Dit gebruik gebruikt automatisch SHA-256 vingerafdruk van het certificaat. Toegevoegd in versie 1.29.0:

Feed in een woordenlijst met het pad naar een PFX-bestand:

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

Met de volgende opdracht wordt een PFX-bestand gegenereerd op basis van uw .key- en PEM-bestand:

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

Verificatie van onderwerpnaam/verlener is een methode om eenvoudiger certificaatrotatie mogelijk te maken. Als uw PFX-bestand zowel de persoonlijke sleutel als het openbare certificaat bevat, kunt u zich aanmelden voor verificatie voor onderwerpnaam/verlener door 'public_certificate' in te stellen op True.

Toegevoegd in versie 0.5.0: het is een woordenlijst met extra claims die door deze ConfidentialClientApplication persoonlijke sleutel worden ondertekend. U kunt bijvoorbeeld {"client_ip": "x.x.x.x.x"} gebruiken. U kunt ook een van de volgende standaardclaims negeren:

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

Een URL die een tokeninstantie identificeert. Deze moet de indeling hebben https://login.microsoftonline.com/your_tenant Standaard gebruiken we https://login.microsoftonline.com/common

Gewijzigd in versie 1.17: u kunt ook vooraf gedefinieerde constante en een opbouwfunctie als volgt gebruiken:

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

(optioneel) Hiermee schakelt u autorisatievalidatie in of uit. Deze parameter is standaard ingesteld op true.

Hiermee stelt u de tokencache in die wordt gebruikt door dit ClientApplication-exemplaar. Standaard wordt er een cache in het geheugen gemaakt en gebruikt.

(optioneel) Uw implementatie van abstracte klasse HttpClient <msal.oauth2cli.http.http_client> Standaard ingesteld op een sessie-exemplaar van aanvragen. Aangezien MSAL 1.11.0 is geconfigureerd, wordt de standaardsessie geconfigureerd om een nieuwe poging te doen bij verbindingsfout. Als u uw eigen http_client opgeeft, is het de plicht van uw http_client om te beslissen of u een nieuwe poging wilt uitvoeren.

(optioneel) Deze wordt doorgegeven aan de verificatieparameter in de onderliggende aanvraagbibliotheek . Dit geldt niet als u ervoor hebt gekozen om uw eigen Http-client door te geven

(optioneel) Deze wordt doorgegeven aan de parameter proxy's in de onderliggende aanvraagbibliotheek . Dit geldt niet als u ervoor hebt gekozen om uw eigen Http-client door te geven

(optioneel) Deze wordt doorgegeven aan de time-outparameter in de onderliggende aanvraagbibliotheek . Dit geldt niet als u ervoor hebt gekozen om uw eigen Http-client door te geven

(optioneel) U kunt uw toepassingsnaam opgeven voor Microsoft telemetriedoeleinden. De standaardwaarde is Geen, betekent dat deze niet wordt doorgegeven aan Microsoft.

(optioneel) U kunt uw toepassingsversie opgeven voor Microsoft telemetriedoeleinden. De standaardwaarde is Geen, betekent dat deze niet wordt doorgegeven aan Microsoft.

(optioneel) Hiermee kunt u een of meer clientmogelijkheden configureren, bijvoorbeeld ["CP1"].

Clientmogelijkheid is bedoeld om de Microsoft identity platform (STS) te informeren waarvoor deze client geschikt is, zodat STS bepaalde functies kan inschakelen. Als de client bijvoorbeeld in staat is om claims uit te voeren, kan STS toegangstokens uitgeven aan resources voor continue toegang tot resources, wetende dat wanneer de resource een claimuitdaging verzendt, de client deze uitdagingen kan afhandelen.

Implementatiedetails: Clientmogelijkheid wordt geïmplementeerd met behulp van de parameter 'claims' op de kabel, voorlopig. MSAL combineert deze in claimsparameter die u later opgeeft via een van de acquire-tokenaanvraag.

(optioneel) Geeft MSAL opdracht om de regionale tokenservice Entra te gebruiken. Deze verouderde functie is alleen beschikbaar voor toepassingen van derden. Alleen acquire_token_for_client() wordt ondersteund.

Ondersteunt 4 waarden:

1. azure_region=None - Deze standaardwaarde betekent dat er geen regio is geconfigureerd. MSAL gebruikt de regio die is gedefinieerd in env var MSAL_FORCE_REGION.

2. azure_region="some_region" - wat betekent dat de opgegeven regio wordt gebruikt.

3. azure_region=True - wat betekent dat MSAL probeert de regio automatisch te detecteren. Dit wordt niet aanbevolen.

4. azure_region=False - betekent dat MSAL geen regio gebruikt.

Nieuw in versie 1.12.0.

(optioneel) MsAL-hardcodes offline_access bereik, waardoor uw app langdurige toegang heeft tot de gegevens van de gebruiker. Als dat niet nodig of ongewenst is voor uw app, kunt u deze parameter nu gebruiken om een uitsluitingslijst met bereiken op te geven, zoals exclude_scopes = ["offline_access"].

MSAL heeft al lang tokens in de cache opgeslagen in de token_cache. Onlangs heeft MSAL ook een concept vanhttp_cache, door automatisch een eindige hoeveelheid niet-token http-antwoorden in de cache op te cachen, zodat lange levensduur PublicClientApplication en ConfidentialClientApplication in sommige situaties beter presterend en responsief zou zijn.

Deze http_cache parameter accepteert elk dicterend object. Indien niet opgegeven, gebruikt MSAL een in-memory dict.

Als uw app een opdrachtregel-app (CLI) is, wilt u uw http_cache behouden voor verschillende CLI-uitvoeringen. De indeling van het persistente bestand kan worden gewijzigd vanwege, maar niet beperkt tot, onstabiel protocol, zodat uw implementatie onverwachte laadfouten tolereert. In het volgende recept ziet u een manier om dit te doen:

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

Inhoud binnen http_cache is goedkoop te verkrijgen. U hoeft ze niet te delen tussen verschillende apps.

Inhoud in de inhoud http_cache bevat geen tokens of persoonlijke informatie (PII). Versleuteling is niet nodig.

Nieuw in versie 1.16.0.

In het verleden zou MSAL verbinding maken met een centraal eindpunt dat zich bevindt om https://login.microsoftonline.com bepaalde metagegevens te verkrijgen, met name wanneer u een onbekende instantie gebruikt. Dit gedrag wordt exemplaardetectie genoemd.

Deze parameter is standaard ingesteld op None, waardoor de instantiedetectie wordt ingeschakeld.

Als u bepaalde instanties kent waarmee MSAL kan werken met as-is, zonder tussenkomst van instantiedetectie, is het aanbevolen patroon:

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

Als u niet van tevoren bepaalde autoriteiten kent, maar toch wilt dat MSAL een instantie accepteert die u wilt verstrekken, kunt u een False onvoorwaardelijke instantiedetectie uitschakelen.

Nieuw in versie 1.19.0.

Deprecated. Gebruik in plaats daarvan enable_broker_on_windows.

Wanneer deze functie is ingeschakeld, kunnen logboeken PII (Persoonsgegevens) bevatten. Dit kan handig zijn bij het oplossen van brokergedrag. Het standaardgedrag is Onwaar.

Nieuw in versie 1.24.0.

Toegevoegd in versie 1.28.0: het is een URL die een OpenID Connect-instantie (OIDC) van de indeling https://contoso.com/tenantidentificeert. MSAL voegt '.well-known/openid-configuration' toe aan de instantie en haalt de OIDC-metagegevens daar op om de eindpunten te achterhalen.

Opmerking: Broker wordt NIET gebruikt voor OIDC-instantie.