ConfidentialClientApplication Osztály

<xref:ClientApplication.__init__>A paramétert kivéve allow_broker a paraméternek is meg kell maradnia None.

Hozzon létre egy alkalmazáspéldányt.

Konstruktor

ConfidentialClientApplication(client_id, client_credential=None, authority=None, validate_authority=True, token_cache=None, http_client=None, verify=True, proxies=None, timeout=None, client_claims=None, app_name=None, app_version=None, client_capabilities=None, azure_region=None, exclude_scopes=None, http_cache=None, instance_discovery=None, allow_broker=None, enable_pii_log=None, oidc_authority=None)

Paraméterek

Name Description
client_id
Kötelező
str

Az alkalmazás client_id rendelkezik, miután regisztrálta a Microsoft Entra felügyeleti központ.
client_credential
Union[dict, str, None]

Itt PublicClientApplicationa Nincs értéket használja.

A ConfidentialClientApplicationkülönböző forgatókönyvekhez számos különböző bemeneti formátumot támogat.

Támogatás ügyfélkód használatával. Csak egy sztringben, például "your client secret".

Támogatás X.509 (.pem) formátumú tanúsítvány használatáhozDeprecated, mert SHA-1 ujjlenyomatot használ,

kivéve, ha továbbra is olyan ADFS-t használ, amely csak az SHA-1 ujjlenyomatot támogatja. Használja a lap későbbi részében dokumentált .pfx beállítást. Hírcsatorna egy diktálásban ebben az formában:


   {
       "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.
   }

Az MSAL Python PEM formátumú "private_key" szükséges. Ha a tanúsítvány PKCS12 (.pfx) formátumban van, X.509 (.pem) formátumba konvertálhatja a következő szerintopenssl pkcs12 -in file.pfx -out file.pem -nodes: . Az ujjlenyomat az alkalmazás Azure Portal való regisztrációjában érhető el. Másik lehetőségként kiszámíthatja az ujjlenyomatot. public_certificate (nem kötelező) egy nyilvános kulcsú tanúsítvány, amely az x5c JWT fejlécen keresztül lesz elküldve. Ez akkor hasznos, ha a tulajdonosnév/kiállító hitelesítését használja, amely lehetővé teszi a tanúsítványok egyszerűbb rotálását. Specifikációnként "a JWS digitális aláírásához használt kulcsnak megfelelő nyilvános kulcsot tartalmazó tanúsítványnak kell lennie az első tanúsítványnak. Ezt a MÁJUS-t további tanúsítványok követik, és minden további tanúsítvány az előző hitelesítéséhez használatos." Előfordulhat azonban, hogy a tanúsítvány kiállítója más megrendelést használ. Tehát, ha a kísérlet egy AADSTS700027 - "A megadott aláírási érték nem egyezik a várt aláírási értékkel" hibával végződik, akkor inkább csak a levél tanúsítványt (PEM/str formátumban) próbálja meg használni.

Az1.13.0-s verzióban hozzáadott, máshonnan beszerzett nyers állítás támogatása:

Ez egy teljesen előre aláírt állítás is lehet, amelyet ön állított össze. Egyszerűen adjon át egy tárolót, amely csak a "client_assertion" kulcsot tartalmazza, például:


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

Ügyféltanúsítványok PFX-fájlokból való olvasásának támogatásaA használat automatikusan a tanúsítvány SHA-256 ujjlenyomatát használja. Hozzáadva az 1.29.0-s verzióhoz:

Hírcsatorna egy PFX-fájl elérési útját tartalmazó szótárban:


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

A következő parancs létrehoz egy .pfx fájlt a .key és a .pem fájlból:


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

A tulajdonos neve/kiállító hitelesítése egy olyan módszer, amely lehetővé teszi a tanúsítványok egyszerűbb rotálását. Ha a .pfx fájl tartalmazza a titkos kulcsot és a nyilvános tanúsítványt is, a Tulajdonos neve/Kiállító hitelesítése beállítást a "public_certificate" értékre Trueállítva választhatja.

Alapértelmezett érték: None
client_claims
dict

Hozzáadva a 0.5.0-s verzióhoz: Ez egy olyan további jogcímek szótára, amelyeket ez ConfidentialClientApplication a titkos kulcs ír alá. Használhatja például a következőt: {"client_ip": "x.x.x.x"}. Felülbírálhatja az alábbi alapértelmezett jogcímeket is:


   {
       "aud": the_token_endpoint,
       "iss": self.client_id,
       "sub": same_as_issuer,
       "exp": now + 10_min,
       "iat": now,
       "jti": a_random_uuid
   }
Alapértelmezett érték: None
authority
str

Egy jogkivonat-szolgáltatót azonosító URL-cím. A formátumnak megfelelőnek kell lennie https://login.microsoftonline.com/your_tenant Alapértelmezés szerint a következőt fogjuk használni: https://login.microsoftonline.com/common

Az 1.17-es verzióban módosult: használhat előre definiált állandót és egy ilyen szerkesztőt is:


   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, ...)
Alapértelmezett érték: None
validate_authority
bool

(nem kötelező) Be- vagy kikapcsolja a hitelesítést. Ez a paraméter alapértelmezés szerint igaz.

Alapértelmezett érték: True
token_cache
TokenCache

Beállítja a ClientApplication-példány által használt jogkivonat-gyorsítótárat. Alapértelmezés szerint a rendszer létrehoz és használ egy memóriabeli gyorsítótárat.

Alapértelmezett érték: None
http_client

(nem kötelező) Az absztrakt HttpClient-osztály <implementációja msal.oauth2cli.http.http_client> Alapértelmezések a kérések munkamenetpéldányára. Az MSAL 1.11.0 óta az alapértelmezett munkamenet úgy lett konfigurálva, hogy megkíséreljen egy újrapróbálkozási kísérletet a csatlakozási hiba miatt. Ha saját http_client biztosít, akkor a http_client feladata eldönteni, hogy újrapróbálkoznak-e.

Alapértelmezett érték: None
verify

(nem kötelező) A rendszer átadja az ellenőrző paraméternek a mögöttes kéréstárban Ez nem vonatkozik, ha a saját Http-ügyfél átadását választotta

Alapértelmezett érték: True
proxies

(nem kötelező) A rendszer átadja a proxy paraméternek a mögöttes kéréstárban Ez nem vonatkozik, ha a saját Http-ügyfél átadását választotta

Alapértelmezett érték: None
timeout

(nem kötelező) A rendszer átadja az időtúllépési paraméternek a mögöttes kéréstárban Ez nem vonatkozik, ha a saját Http-ügyfél átadását választotta

Alapértelmezett érték: None
app_name

(nem kötelező) Megadhatja az alkalmazás nevét Microsoft telemetriai célokra. Az alapértelmezett érték Nincs, ami azt jelenti, hogy a rendszer nem adja át Microsoft.

Alapértelmezett érték: None
app_version

(nem kötelező) Az alkalmazás verzióját Microsoft telemetriai célokra is megadhatja. Az alapértelmezett érték Nincs, ami azt jelenti, hogy a rendszer nem adja át Microsoft.

Alapértelmezett érték: None
client_capabilities
list[str]

(nem kötelező) Lehetővé teszi egy vagy több ügyfélképesség(pl. ["CP1") konfigurálását.

Az ügyfélképesség célja, hogy tájékoztassa a Microsoft Identitásplatform (STS) arról, hogy mire képes ez az ügyfél, így az STS dönthet úgy, hogy bekapcsol bizonyos funkciókat. Ha például az ügyfél képes kezelni a jogcímekkel kapcsolatos kihívásokat, az STS folyamatos hozzáférés-kiértékelési (CAE) hozzáférési jogkivonatokat bocsáthat ki az erőforrások számára, tudva, hogy amikor az erőforrás jogcímkérdést bocsát ki, az ügyfél képes lesz kezelni ezeket a kihívásokat.

Megvalósítás részletei: Az ügyfélképesség egyelőre a vezeték "jogcím" paraméterével implementálva van. Az MSAL a jogcímparaméterbe egyesíti őket, amelyet később a beolvasási jogkivonat-kérelem egyikén fog megadni.

Alapértelmezett érték: None
azure_region
str

(nem kötelező) Utasítja az MSAL-t, hogy használja az Entra regionális jogkivonat-szolgáltatást. Ez az örökölt funkció csak külső alkalmazások számára érhető el. Kizárólag az acquire_token_for_client() támogatott.

4 értéket támogat:

  1. azure_region=None – Ez az alapértelmezett érték azt jelenti, hogy nincs régió konfigurálva. Az MSAL az env varban MSAL_FORCE_REGIONdefiniált régiót fogja használni.

  2. azure_region="some_region" - vagyis a megadott régiót használja a rendszer.

  3. azure_region=True - vagyis az MSAL megpróbálja automatikusan észlelni a régiót. Ez nem ajánlott.

  4. azure_region=False - vagyis az MSAL nem használ régiót.

Note

A régió automatikus felderítését virtuális gépeken és Azure Functions tesztelték. Megbízhatatlan.

Az ezzel a beállítással rendelkező alkalmazásoknak rövid időtúllépést kell konfigurálnia.

További részletekért és a régiós sztring értékeiért

lásd: https://learn.microsoft.com/entra/msal/dotnet/resources/region-discovery-troubleshooting

Az 1.12.0-s verzió újdonságai.

Alapértelmezett érték: None
exclude_scopes
list[str]

(nem kötelező) A korábbi MSAL-merevlemezek offline_access hatókört, ami lehetővé tenné, hogy az alkalmazás hosszabb ideig hozzáférjen a felhasználói adatokhoz. Ha ez szükségtelen vagy nem kívánatos az alkalmazás számára, most ezzel a paraméterrel megadhat egy kizárási listát a hatókörökről, például exclude_scopes = ["offline_access"].

Alapértelmezett érték: None
http_cache
dict

Az MSAL már régóta gyorsítótáraz jogkivonatokat a token_cache. A közelmúltban az MSAL is bevezette a fogalmat http_cache, azáltal, hogy automatikusan gyorsítótárazott néhány véges mennyiségű nem token http-válaszok, így a hosszú élettartamúPublicClientApplication , és ConfidentialClientApplication nagyobb teljesítményű és rugalmas bizonyos helyzetekben.

Ez a http_cache paraméter bármilyen diktálásszerű objektumot elfogad. Ha nincs megadva, az MSAL egy memóriabeli diktáltot fog használni.

Ha az alkalmazás parancssori alkalmazás , akkor a http_cache különböző parancssori felületi futtatásokon keresztül is meg szeretné őrizni. A megőrzött fájl formátuma instabil protokoll miatt változhat, de nem kizárólagosan, így a megvalósításnak el kell viselnie a váratlan betöltési hibákat. A következő recept bemutatja ennek módját:


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

A belső http_cache tartalom olcsó beszerezhető. Nem kell megosztani őket a különböző alkalmazások között.

A benne található http_cache tartalom nem tartalmaz jogkivonatokat és személyazonosításra alkalmas adatokat (PII). A titkosítás szükségtelen.

Az 1.16.0-s verzió újdonságai.

Alapértelmezett érték: None
instance_discovery
<xref:boolean>

Az MSAL korábban egy központi végponthoz https://login.microsoftonline.com kapcsolódott, ahol bizonyos metaadatokat szerezhet be, különösen ismeretlen szolgáltató használata esetén. Ezt a viselkedést példányfelderítésnek nevezzük.

Ez a paraméter alapértelmezés szerint Nincs, ami lehetővé teszi a példányfelderítést.

Ha ismer néhány olyan hatóságot, amely lehetővé teszi, hogy az MSAL as-isműködjön, példányfelderítés nélkül, a javasolt minta a következő:


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

Ha korábban nem ismer bizonyos hatóságokat, de továbbra is azt szeretné, hogy az MSAL elfogadjon bármilyen, Ön által megadott hatóságot, használhatja False a példányfelderítés feltétel nélküli letiltását.

Az 1.19.0-s verzió újdonságai.

Alapértelmezett érték: None
allow_broker
<xref:boolean>

Deprecated. Használja inkább a enable_broker_on_windows.

Alapértelmezett érték: None
enable_pii_log
<xref:boolean>

Ha engedélyezve van, a naplók tartalmazhatnak PII-t (személyes azonosításra alkalmas adatokat). Ez hasznos lehet a közvetítők viselkedésének hibaelhárításában. Az alapértelmezett viselkedés hamis.

Az 1.24.0-s verzió újdonságai.

Alapértelmezett érték: None
oidc_authority
str

Hozzáadva az 1.28.0-s verzióhoz: Ez egy URL-cím, amely azonosítja a formátum https://contoso.com/tenantOpenID Connect (OIDC) szolgáltatóját. Az MSAL hozzáfűzi a ".well-known/openid-configuration" parancsot a szolgáltatóhoz, és onnan kéri le az OIDC metaadatait a végpontok megállapításához.

Megjegyzés: A közvetítő nem használható az OIDC-szolgáltatóhoz.

Alapértelmezett érték: None

Metódusok

acquire_token_for_client

Jogkivonatot szerez be az aktuális bizalmas ügyfélhez, nem végfelhasználóhoz.

Mivel az MSAL Python 1.23-at, automatikusan megkeresi a gyorsítótárból származó jogkivonatot, és csak akkor küld kérést az identitásszolgáltatónak, ha a gyorsítótár nem működik.
acquire_token_on_behalf_of

Jogkivonatot szerez be az OBO-folyamat használatával.

Az aktuális alkalmazás egy középszintű szolgáltatás, amelyet egy végfelhasználót jelképező jogkivonattal hívtak meg. Az aktuális alkalmazás az ilyen jogkivonatot (más néven felhasználói állítást) használhatja egy másik jogkivonat kérésére a downstream webes API eléréséhez az adott felhasználó nevében. A részletes dokumentációt itt találja.

A jelenlegi középső szintű alkalmazás nem rendelkezik felhasználói beavatkozással a hozzájárulás beszerzéséhez. Ebből a cikkből megtudhatja, hogyan szerezhet előzetes hozzájárulást a középső szintű alkalmazáshoz. https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application
remove_tokens_for_client

Távolítsa el az aktuális ügyfélhez korábban beszerzett acquire_token_for_client összes jogkivonatot.

acquire_token_for_client

Jogkivonatot szerez be az aktuális bizalmas ügyfélhez, nem végfelhasználóhoz.

Mivel az MSAL Python 1.23-at, automatikusan megkeresi a gyorsítótárból származó jogkivonatot, és csak akkor küld kérést az identitásszolgáltatónak, ha a gyorsítótár nem működik.

acquire_token_for_client(scopes, claims_challenge=None, fmi_path=None, **kwargs)

Paraméterek

Name Description
scopes
Kötelező
list[str]

(Kötelező) Védett API-k (erőforrás) eléréséhez kért hatókörök.
claims_challenge

A claims_challenge paraméter claims_challenge irányelv formájában kért konkrét jogcímeket kér az erőforrás-szolgáltatótól a UserInfo végpontról és/vagy az azonosító jogkivonatból és/vagy hozzáférési jogkivonatból visszaadandó www-hitelesítés fejlécében. Ez egy JSON-objektum sztringje, amely az ezekről a helyekről kért jogcímlistákat tartalmazza.

Alapértelmezett érték: None
fmi_path
str

Optional. Az összevont felügyelt identitás (FMI) hitelesítő elérési útja. Ha meg van adva, a rendszer paraméterként küldi el a fmi_path jogkivonat-kérelem törzsében, és az eredményül kapott jogkivonatot külön gyorsítótárazza a rendszer, hogy a különböző FMI-útvonalak ne oszthassák meg a gyorsítótárazott jogkivonatokat. Gyakorlati példa: 


   result = cca.acquire_token_for_client(
       scopes=["api://resource/.default"],
       fmi_path="SomeFmiPath/FmiCredentialPath",
   )
Alapértelmezett érték: None

Válaszok

Típus Description

A Microsoft Entra json-válaszát képviselő diktálás:

  • A sikeres válasz "access_token" kulcsot tartalmazna,

  • a hibaválasz "error" (hiba) és általában "error_description" szöveget tartalmazna.

acquire_token_on_behalf_of

Jogkivonatot szerez be az OBO-folyamat használatával.

Az aktuális alkalmazás egy középszintű szolgáltatás, amelyet egy végfelhasználót jelképező jogkivonattal hívtak meg. Az aktuális alkalmazás az ilyen jogkivonatot (más néven felhasználói állítást) használhatja egy másik jogkivonat kérésére a downstream webes API eléréséhez az adott felhasználó nevében. A részletes dokumentációt itt találja.

A jelenlegi középső szintű alkalmazás nem rendelkezik felhasználói beavatkozással a hozzájárulás beszerzéséhez. Ebből a cikkből megtudhatja, hogyan szerezhet előzetes hozzájárulást a középső szintű alkalmazáshoz. https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow#gaining-consent-for-the-middle-tier-application

acquire_token_on_behalf_of(user_assertion, scopes, claims_challenge=None, **kwargs)

Paraméterek

Name Description
user_assertion
Kötelező
str

Az alkalmazás által már fogadott bejövő jogkivonat
scopes
Kötelező
list[str]

A downstream API (egy erőforrás) által igényelt hatókörök.
claims_challenge

A claims_challenge paraméter claims_challenge irányelv formájában kért konkrét jogcímeket kér az erőforrás-szolgáltatótól a UserInfo végpontról és/vagy az azonosító jogkivonatból és/vagy hozzáférési jogkivonatból visszaadandó www-hitelesítés fejlécében. Ez egy JSON-objektum sztringje, amely az ezekről a helyekről kért jogcímlistákat tartalmazza.

Alapértelmezett érték: None

Válaszok

Típus Description

A Microsoft Entra json-válaszát képviselő diktálás:

  • A sikeres válasz "access_token" kulcsot tartalmazna,

  • a hibaválasz "error" (hiba) és általában "error_description" szöveget tartalmazna.

remove_tokens_for_client

Távolítsa el az aktuális ügyfélhez korábban beszerzett acquire_token_for_client összes jogkivonatot.

remove_tokens_for_client()