ClientApplication Třída

Vaše aplikace má po registraci na Centrum pro správu Microsoft Entra client_id.

Pro PublicClientApplication, použijete none here.

Pro ConfidentialClientApplicationrůzné scénáře podporuje mnoho různých vstupních formátů.

Podpora použití tajného klíče klienta Stačí ho nakrátit řetězcem, například "your client secret".

Podpora použití certifikátu ve formátu X.509 (.pem), protože používá kryptografický otisk SHA-1

pokud stále nepoužíváte ADFS, která podporuje jenom kryptografický otisk SHA-1. Použijte možnost .pfx zdokumentovanou později na této stránce. Informační kanál v diktování v tomto formuláři:

   {
       "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 vyžaduje "private_key" ve formátu PEM. Pokud je váš certifikát ve formátu PKCS12 (.pfx), můžete ho převést do formátu X.509 (.pem) podle openssl pkcs12 -in file.pfx -out file.pem -nodesformátu . Kryptografický otisk je k dispozici v registraci vaší aplikace v Azure Portal. Případně můžete kryptografický otisk vypočítat. public_certificate (volitelné) je certifikát veřejného klíče, který se odešle prostřednictvím hlavičky JWT x5c. To je užitečné, když používáte ověřování názvu subjektu nebo vystavitele , což je přístup, který umožňuje snadnější obměně certifikátů. Podle specifikace "certifikát obsahující veřejný klíč odpovídající klíči použitému k digitálnímu podepsání JWS musí být prvním certifikátem. Za tímto účelem mohou následovat další certifikáty, přičemž každý další certifikát je ten, který slouží k certifikaci předchozího certifikátu." Vystavitel vašeho certifikátu ale může použít jiné pořadí. Takže pokud váš pokus skončí chybou AADSTS700027 – "Zadaná hodnota podpisu neodpovídá očekávané hodnotě podpisu", můžete místo toho použít pouze certifikát typu list (ve formátu PEM/str).

Podpora nezpracovaného kontrolního výrazu získaného odjinudpřidaného ve verzi 1.13.0:

Může to být také zcela předem podepsaný kontrolní výraz, který jste vytvořili sami. Jednoduše předejte kontejner obsahující pouze klíč "client_assertion", například takto:

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

Podpora čtení klientských certifikátů ze souborů PFXUUUusu automaticky použije kryptografický otisk certifikátu SHA-256. Přidáno ve verzi 1.29.0:

Informační kanál ve slovníku obsahujícím cestu k souboru 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)",
   }

Následující příkaz vygeneruje soubor .pfx z vašeho souboru .key a .pem:

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

Ověřování názvu subjektu nebo vystavitele je přístup, který umožňuje snadnější obměně certifikátů. Pokud váš soubor .pfx obsahuje privátní klíč i veřejný certifikát, můžete se rozhodnout pro ověření názvu subjektu nebo vystavitele nastavením "public_certificate" na True.

Přidáno ve verzi 0.5.0: Jedná se o slovník dodatečných deklarací identity, které by podepsal tento ConfidentialClientApplication privátní klíč. Můžete například použít {"client_ip": "x.x.x.x"}. Můžete také přepsat některou z následujících výchozích deklarací identity:

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

Adresa URL, která identifikuje autoritu tokenu. Měl by mít formát. https://login.microsoftonline.com/your_tenant Ve výchozím nastavení použijeme https://login.microsoftonline.com/common

Změněno ve verzi 1.17: Můžete také použít předdefinovanou konstantu a tvůrce takto:

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

(volitelné) Zapne nebo vypne ověření autority. Tento parametr má výchozí hodnotu true.

Nastaví mezipaměť tokenů používanou touto instancí ClientApplication. Ve výchozím nastavení se vytvoří a použije mezipaměť v paměti.

(volitelné) Implementace abstraktní třídy HttpClient <msal.oauth2cli.http.http_client> Defaults to a requests session instance. Vzhledem k tomu, že MSAL 1.11.0, je výchozí relace nakonfigurovaná tak, aby se pokusila o jeden pokus o chybu připojení. Pokud poskytujete vlastní http_client, bude vaší povinností http_client rozhodnout, jestli se má opakovat.

(volitelné) Předá se do parametru ověření v podkladové knihovně požadavků . To neplatí, pokud jste se rozhodli předat vlastního klienta HTTP.

(volitelné) Předá se parametru proxy v podkladové knihovně požadavků . To neplatí, pokud jste se rozhodli předat vlastního klienta HTTP.

(volitelné) Předá se parametru časového limitu v podkladové knihovně požadavků . To neplatí, pokud jste se rozhodli předat vlastního klienta HTTP.

(volitelné) Název aplikace můžete zadat pro účely Microsoft telemetrie. Výchozí hodnota je None, znamená to, že se nepředá Microsoft.

(volitelné) Verzi aplikace můžete zadat pro účely Microsoft telemetrie. Výchozí hodnota je None, znamená to, že se nepředá Microsoft.

(volitelné) Umožňuje konfiguraci jedné nebo více možností klienta, např. ["CP1"].

Klientská funkce je určená k informování Microsoft identity platform (STS), k čemu je tento klient schopný, aby se služba stS mohla rozhodnout zapnout určité funkce. Pokud například klient dokáže zpracovat výzvu deklarací identity, může služba STS vydávat přístupové tokeny caE (Continuous Access Evaluation) k prostředkům, protože když prostředek vygeneruje výzvu deklarací identity , bude klient schopen tyto výzvy zvládnout.

Podrobnosti o implementaci: Funkce klienta se teď implementuje pomocí parametru deklarací identity v drátě. KNIHOVNA MSAL je zkombinuje do parametru deklarací identity , který později poskytnete prostřednictvím některého požadavku na získání tokenu.

(volitelné) Dává službě MSAL pokyn, aby používala službu tokenů oblasti Entra. Tato starší verze funkce je dostupná jenom pro aplikace první strany. Podporuje se jenom acquire_token_for_client().

Podporuje 4 hodnoty:

1. azure_region=None – Tato výchozí hodnota znamená, že není nakonfigurována žádná oblast. MSAL použije oblast definovanou v env var MSAL_FORCE_REGION.

2. azure_region="some_region" - znamená, že se použije zadaná oblast.

3. azure_region=True – znamená to, že msAL se pokusí automaticky zjistit oblast. Toto se nedoporučuje.

4. azure_region=False – znamená to, že MSAL nebude používat žádnou oblast.

Novinka ve verzi 1.12.0

(volitelné) V minulosti pevné kódy MSAL offline_access rozsah, což by vaší aplikaci umožnilo prodloužit přístup k datům uživatele. Pokud to není pro vaši aplikaci zbytečné nebo nežádoucí, můžete teď pomocí tohoto parametru zadat seznam oborů vyloučení, například exclude_scopes = ["offline_access"].

MSAL už dlouho do mezipaměti tokeny v systému token_cache. Knihovna MSAL nedávno zavedla také koncept http_cache, díky automatickému ukládání některých konečných odpovědí http do mezipaměti, takže dlouhodobéPublicClientApplication a ConfidentialClientApplication v některých situacích by byly výkonnější a responzivní.

Tento http_cache parametr přijímá jakýkoli objekt podobný diktování. Pokud není k dispozici, msAL použije diktování v paměti.

Pokud se jedná o aplikaci příkazového řádku (CLI), měli byste zachovat http_cache v různých spuštěních rozhraní příkazového řádku. Trvalý formát souboru se může změnit kvůli nestabilnímu protokolu, nikoli však kvůli nestabilnímu protokolu, takže implementace bude tolerovat neočekávané chyby načítání. Následující recept ukazuje způsob, jak to udělat:

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

Obsah uvnitř http_cache jsou levné získat. Není nutné je sdílet mezi různými aplikacemi.

Obsah uvnitř http_cache nebude obsahovat žádné tokeny ani identifikovatelné osobní údaje (PII). Šifrování není nutné.

Novinka ve verzi 1.16.0

Služba MSAL se historicky připojuje k centrálnímu koncovému bodu umístěnému https://login.microsoftonline.com za účelem získání některých metadat, zejména při použití neznámé autority. Toto chování se označuje jako zjišťování instancí.

Tento parametr má výchozí hodnotu None, která umožňuje zjišťování instancí.

Pokud znáte některé autority, které službě MSAL umožňují pracovat s as-is, aniž byste museli provádět zjišťování instancí, doporučuje se:

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

Pokud některé autority předem neznáte, ale přesto chcete, aby služba MSAL přijala jakoukoli autoritu False , kterou poskytnete, můžete použít k bezpodmínečně zakázání zjišťování instancí.

Novinka ve verzi 1.19.0

Deprecated. Místo toho použijte enable_broker_on_windows .

Pokud je tato možnost povolená, můžou protokoly obsahovat PII (osobní identifikovatelné informace). To může být užitečné při řešení potíží s chováním zprostředkovatele. Výchozí chování je False.

Novinka ve verzi 1.24.0

Přidáno ve verzi 1.28.0: Jedná se o adresu URL, která identifikuje autoritu OpenID Connect (OIDC) formátu https://contoso.com/tenant. MSAL připojí k autoritě ".well-known/openid-configuration" a načte metadata OIDC odtud, aby bylo možné zjistit koncové body.

Poznámka: Zprostředkovatel nebude použit pro autoritu OIDC.