ClientApplication Osztály

Ezt az osztályt általában nem használja közvetlenül. Használja helyette az alosztályokat: PublicClientApplication és ConfidentialClientApplication.

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

Konstruktor

ClientApplication(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ához. 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, 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_by_auth_code_flow

Ellenőrizze az átirányított hitelesítési választ, és szerezze be a jogkivonatokat.

Automatikusan biztosít nem szándékos védelmet.
acquire_token_by_authorization_code

Az engedélyezési kód megadásának második fele.
acquire_token_by_refresh_token

Jogkivonat(ok) beszerzése máshonnan beszerzett frissítési jogkivonat (RT) alapján.

Ezt a módszert csak akkor használja, ha máshonnan származó régi RT-kkel rendelkezik, és most át szeretné őket migrálni az MSAL-be. A metódus meghívásával új jogkivonatok automatikusan az MSAL-ba kerülnek.

Nem kell ezt a módszert használnia, ha már használja az MSAL-t. Az MSAL automatikusan fenntartja az RT-t a tokengyorsítótárában, és híváskor acquire_token_silentlekérhető egy hozzáférési jogkivonat.
acquire_token_by_username_password

Jogkivonatot kér le egy adott erőforráshoz a felhasználói hitelesítő adatokon keresztül.

Ezen a lapon megtekintheti a felhasználónév-jelszó folyamatának korlátozásait. https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication

[Elavult] Ez az API elavult a nyilvános ügyfélfolyamatok esetében, és egy későbbi kiadásban el lesz távolítva. Inkább használjon biztonságosabb folyamatot. Migrálási útmutató: https://aka.ms/msal-ropc-migration
acquire_token_silent

Hozzáférési jogkivonat beszerzése adott fiókhoz felhasználói beavatkozás nélkül.

Ugyanazokkal a paraméterekkel rendelkezik, mint a acquire_token_silent_with_error. A különbség a visszatérési érték viselkedése. Ez a metódus a gyorsítótár üres és a frissítési hibát egyetlen eredményértékben egyesíti, a Nincs értékben. Ha az alkalmazás nem törődik a tokenek frissítési hibájával a tokengyorsítótár-keresés során, akkor ez a módszer egyszerűbb és ajánlott.
acquire_token_silent_with_error

Hozzáférési jogkivonat beszerzése adott fiókhoz felhasználói beavatkozás nélkül.

Ez vagy egy érvényes hozzáférési jogkivonat gyorsítótárból való keresésével, vagy egy érvényes frissítési jogkivonat gyorsítótárból való keresésével, majd automatikusan egy új hozzáférési jogkivonat beváltásához történik.

Ez a módszer megkülönbözteti az üres gyorsítótárat a tokenfrissítési hibától. Ha az alkalmazás a tokengyorsítótár-keresés során pontos jogkivonat-frissítési hibát észlel, akkor ez a módszer megfelelő. Ellenkező esetben a másik módszer acquire_token_silent használata javasolt.
get_accounts

Lekérheti a korábban bejelentkezett fiókok listáját, például a gyorsítótárban létezik.

A fiók később használható a acquire_token_silent jogkivonatok megkereséséhez.
get_authorization_request_url

Létrehoz egy URL-címet az engedélyezési kód megadásának elindításához.
initiate_auth_code_flow

Hitelesítési kódfolyamat kezdeményezése.

Később, amikor a válasz eléri a redirect_uri, elvégezheti acquire_token_by_auth_code_flow a hitelesítést/engedélyezést.
is_pop_supported

Igaz értéket ad vissza, ha ez az ügyfél támogatja a birtoklás igazolása hozzáférési jogkivonatot.
remove_account

Kijelentkeztetés és felejtés a tokengyorsítótárból

acquire_token_by_auth_code_flow

Ellenőrizze az átirányított hitelesítési választ, és szerezze be a jogkivonatokat.

Automatikusan biztosít nem szándékos védelmet.

acquire_token_by_auth_code_flow(auth_code_flow, auth_response, scopes=None, **kwargs)

Paraméterek

Name Description
auth_code_flow
Kötelező
dict

Ugyanaz a diktálás, amelyet a következő adott initiate_auth_code_flowvissza: .
auth_response
Kötelező
dict

A hitelesítési kiszolgálótól kapott lekérdezési sztring diktálása.
scopes
list[str]

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

Legtöbbször üresen hagyhatja.

Ha több erőforráshoz kért felhasználói hozzájárulást, itt meg kell adnia a szükséges initiate_auth_code_flowrészhalmazt.

Az OAuth2-t főként egyszeri szolgáltatásokhoz tervezték, ahol a jogkivonatok mindig ugyanarra az erőforrásra vannak szánva, és az egyetlen változás a hatókörökben van. A Microsoft Entra több külső erőforráshoz is kibocsáthatók jogkivonatok. Több erőforráshoz is kérhet engedélyezési kódot, de a beváltáskor a jogkivonat csak egy címzettnek, a célközönségnek szól. A fejlesztőnek tehát meg kell adnia egy hatókört, hogy korlátozhassuk a megfelelő célközönség számára kibocsátandó jogkivonatot.

Alapértelmezett érték: None

Válaszok

Típus Description

  • A "access_token" és/vagy "id_token" tartalmú diktálás többek között attól függ, hogy milyen hatókört használtak. (Lásd https://tools.ietf.org/html/rfc6749#section-5.1)

  • "error", opcionálisan "error_description", "error_uri" tartalmú diktálás. (Ez vagy ez vagy az)

  • A legtöbb ügyféloldali adathiba ValueError kivételt eredményezne. A használati minta tehát protokolladatok nélkül is lehetséges:

    
   def authorize():  # A controller in a web app
       try:
           result = msal_app.acquire_token_by_auth_code_flow(
               session.get("flow", {}), request.args)
           if "error" in result:
               return render_template("error.html", result)
           use(result)  # Token(s) are available in result and cache
       except ValueError:  # Usually caused by CSRF
           pass  # Simply ignore them
       return redirect(url_for("index"))

acquire_token_by_authorization_code

Az engedélyezési kód megadásának második fele.

acquire_token_by_authorization_code(code, scopes, redirect_uri=None, nonce=None, claims_challenge=None, **kwargs)

Paraméterek

Name Description
code
Kötelező

Az engedélyezési kiszolgálótól visszaadott engedélyezési kód.
scopes
Kötelező
list[str]

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

Ha több erőforráshoz kért felhasználói hozzájárulást, itt általában az AuthCode-ban megkövetelt részhalmazt kell megadnia.

Az OAuth2-t főként egyszeri szolgáltatásokhoz tervezték, ahol a jogkivonatok mindig ugyanarra az erőforrásra vannak szánva, és az egyetlen módosítás a hatókörökben van. A Microsoft Entra több külső erőforráshoz is kibocsáthatók jogkivonatok. Több erőforráshoz is kérhet engedélyezési kódot, de a beváltáskor a jogkivonat csak egy címzettnek, a célközönségnek szól. A fejlesztőnek tehát meg kell adnia egy hatókört, hogy korlátozhassuk a megfelelő célközönség számára kibocsátandó jogkivonatot.
nonce

Ha híváskor get_authorization_request_urlnemet adott meg, akkor itt is meg kell adni ugyanazt a nem elemet, hogy érvényesítsük. A rendszer kivételt hoz létre, ha az azonosító jogkivonatában nem szereplő eltérés nem egyezik.

Alapértelmezett érték: None
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
redirect_uri
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_by_refresh_token

Jogkivonat(ok) beszerzése máshonnan beszerzett frissítési jogkivonat (RT) alapján.

Ezt a módszert csak akkor használja, ha máshonnan származó régi RT-kkel rendelkezik, és most át szeretné őket migrálni az MSAL-be. A metódus meghívásával új jogkivonatok automatikusan az MSAL-ba kerülnek.

Nem kell ezt a módszert használnia, ha már használja az MSAL-t. Az MSAL automatikusan fenntartja az RT-t a tokengyorsítótárában, és híváskor acquire_token_silentlekérhető egy hozzáférési jogkivonat.

acquire_token_by_refresh_token(refresh_token, scopes, **kwargs)

Paraméterek

Name Description
refresh_token
Kötelező
str

A régi frissítési jogkivonat sztringként.
scopes
Kötelező
list

A hatókörök ehhez a régi RT-hez társulnak. Minden hatókörnek Microsoft Identitásplatform (v2) formátumban kell lennie. Lásd : A hatókörök nem erőforrások.

Válaszok

Típus Description

  • A diktálás "hibát" és más kulcsokat tartalmaz, amikor hiba történt.

  • A diktálás nem tartalmaz "hiba" kulcsot, ami azt jelenti, hogy a migrálás sikeres volt.

acquire_token_by_username_password

Jogkivonatot kér le egy adott erőforráshoz a felhasználói hitelesítő adatokon keresztül.

Ezen a lapon megtekintheti a felhasználónév-jelszó folyamatának korlátozásait. https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication

[Elavult] Ez az API elavult a nyilvános ügyfélfolyamatok esetében, és egy későbbi kiadásban el lesz távolítva. Inkább használjon biztonságosabb folyamatot. Migrálási útmutató: https://aka.ms/msal-ropc-migration

acquire_token_by_username_password(username, password, scopes, claims_challenge=None, auth_scheme=None, **kwargs)

Paraméterek

Name Description
username
Kötelező
str

Általában egy UPN e-mail-cím formájában.
password
Kötelező
str

A jelszó.
scopes
Kötelező
list[str]

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
auth_scheme
object

Megadhat egy objektumot msal.auth_scheme.PopAuthScheme , hogy az MSAL megkapja a birtoklás igazolása (POP) jogkivonatot.

Az 1.26.0-s verzió újdonságai.

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_silent

Hozzáférési jogkivonat beszerzése adott fiókhoz felhasználói beavatkozás nélkül.

Ugyanazokkal a paraméterekkel rendelkezik, mint a acquire_token_silent_with_error. A különbség a visszatérési érték viselkedése. Ez a metódus a gyorsítótár üres és a frissítési hibát egyetlen eredményértékben egyesíti, a Nincs értékben. Ha az alkalmazás nem törődik a tokenek frissítési hibájával a tokengyorsítótár-keresés során, akkor ez a módszer egyszerűbb és ajánlott.

acquire_token_silent(scopes, account, authority=None, force_refresh=False, claims_challenge=None, auth_scheme=None, **kwargs)

Paraméterek

Name Description
scopes
Kötelező
account
Kötelező
authority
Alapértelmezett érték: None
force_refresh
Alapértelmezett érték: False
claims_challenge
Alapértelmezett érték: None
auth_scheme
Alapértelmezett érték: None

Válaszok

Típus Description

  • Ha a gyorsítótár-keresés sikeres volt, a diktálás nem tartalmaz "hiba" kulcsot, és általában egy "access_token" kulcsot tartalmaz.

  • Nincs, ha a gyorsítótár-keresés nem hoz létre jogkivonatot.

acquire_token_silent_with_error

Hozzáférési jogkivonat beszerzése adott fiókhoz felhasználói beavatkozás nélkül.

Ez vagy egy érvényes hozzáférési jogkivonat gyorsítótárból való keresésével, vagy egy érvényes frissítési jogkivonat gyorsítótárból való keresésével, majd automatikusan egy új hozzáférési jogkivonat beváltásához történik.

Ez a módszer megkülönbözteti az üres gyorsítótárat a tokenfrissítési hibától. Ha az alkalmazás a tokengyorsítótár-keresés során pontos jogkivonat-frissítési hibát észlel, akkor ez a módszer megfelelő. Ellenkező esetben a másik módszer acquire_token_silent használata javasolt.

acquire_token_silent_with_error(scopes, account, authority=None, force_refresh=False, claims_challenge=None, auth_scheme=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.
account
Kötelező

(Kötelező) Az egyik fiókobjektum, amelyet a következő adott get_accountsvissza: . Az MSAL Python 1.23-tól kezdve a None bemenet NO-OP lesz, és mindig visszatérNone.
force_refresh

Ha igaz, akkor kihagyja az Access-jogkivonat keresését, és megpróbál megkeresni egy frissítési jogkivonatot egy új hozzáférési jogkivonat beszerzéséhez.

Alapértelmezett érték: False
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
auth_scheme
object

Megadhat egy objektumot msal.auth_scheme.PopAuthScheme , hogy az MSAL megkapja a birtoklás igazolása (POP) jogkivonatot.

Az 1.26.0-s verzió újdonságai.

Alapértelmezett érték: None
authority
Alapértelmezett érték: None

Válaszok

Típus Description

  • Ha a gyorsítótár-keresés sikeres volt, a diktálás nem tartalmaz "hiba" kulcsot, és általában egy "access_token" kulcsot tartalmaz.

  • Nincs, ha egyszerűen nincs token a gyorsítótárban.

  • Hibakulcsot tartalmazó diktálás, amikor a jogkivonat frissítése meghiúsult.

get_accounts

Lekérheti a korábban bejelentkezett fiókok listáját, például a gyorsítótárban létezik.

A fiók később használható a acquire_token_silent jogkivonatok megkereséséhez.

get_accounts(username=None)

Paraméterek

Name Description
username

Csak ezzel a felhasználónévvel rendelkező fiókok szűrése. A kis- és nagybetűk érzéketlenek.

Alapértelmezett érték: None

Válaszok

Típus Description

Fiókobjektumok listája. Minden fiók egy diktálás. Egyelőre csak a "felhasználónév" mezőt dokumentáljuk. Az alkalmazás dönthet úgy, hogy megjeleníti ezeket az információkat a végfelhasználónak, és lehetővé teszi a felhasználónak, hogy válasszon egyet a fiókjából a folytatáshoz.

get_authorization_request_url

Létrehoz egy URL-címet az engedélyezési kód megadásának elindításához.

get_authorization_request_url(scopes, login_hint=None, state=None, redirect_uri=None, response_type='code', prompt=None, nonce=None, domain_hint=None, claims_challenge=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.
state
str

Az OAuth2 ajánlott a CSRF-védelemhez.

Alapértelmezett érték: None
login_hint
str

A felhasználó azonosítója. Általában egyszerű felhasználónév (UPN).

Alapértelmezett érték: None
redirect_uri
str

A hatóság válaszának beérkezésekor visszaadandó cím.

Alapértelmezett érték: None
response_type
str

Az alapértelmezett érték egy OAuth2 engedélyezési kód megadásához tartozó "kód".

Használhat más tartalmakat, például a "id_token" vagy a "tokent", amelyek implicit támogatást aktiválnának, de ez nem ajánlott.

Alapértelmezett érték: code
prompt
str

Alapértelmezés szerint a rendszer nem küld parancssori értéket, még sztringet "none"sem. Explicit módon kell megadnia egy értéket. Az érvényes értékek a következőben <xref:msal.Prompt>definiált állandók: .

Alapértelmezett érték: None
nonce

Kriptográfiailag véletlenszerű érték, amelyet a visszajátszási támadások enyhítésére használnak. Lásd még az OIDC specifikációit.

Alapértelmezett érték: None
domain_hint

Lehet a "fogyasztók" vagy a "szervezetek" vagy a "contoso.com" bérlői tartomány. Ha tartalmazza, akkor kihagyja az e-mail-alapú felderítési folyamatot, amelyen a felhasználó végighalad a bejelentkezési oldalon, ami kissé leegyszerűsített felhasználói élményt eredményez. További információ az Auth Code Flow-dokumentumban és domain_hint dokumentumban elérhető lehetséges értékekről.

Alapértelmezett érték: None
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

Az engedélyezési URL-cím sztringként.

initiate_auth_code_flow

Hitelesítési kódfolyamat kezdeményezése.

Később, amikor a válasz eléri a redirect_uri, elvégezheti acquire_token_by_auth_code_flow a hitelesítést/engedélyezést.

initiate_auth_code_flow(scopes, redirect_uri=None, state=None, prompt=None, login_hint=None, domain_hint=None, claims_challenge=None, max_age=None, response_mode=None)

Paraméterek

Name Description
scopes
Kötelező
list

A kis- és nagybetűket megkülönböztető sztringek listája.
redirect_uri
str

Optional. Ha nincs megadva, a kiszolgáló az előre regisztráltat fogja használni.

Alapértelmezett érték: None
state
str

Az ügyfél által a kérés és a visszahívás közötti állapot fenntartására használt átlátszatlan érték. Ha nem jelenik meg, ez a kódtár automatikusan létrehoz egyet belsőleg.

Alapértelmezett érték: None
prompt
str

Alapértelmezés szerint a rendszer nem küld parancssori értéket, még sztringet "none"sem. Explicit módon kell megadnia egy értéket. Az érvényes értékek a következőben <xref:msal.Prompt>definiált állandók: .

Alapértelmezett érték: None
login_hint
str

Optional. A felhasználó azonosítója. Általában egyszerű felhasználónév (UPN).

Alapértelmezett érték: None
domain_hint

Lehet a "fogyasztók" vagy a "szervezetek" vagy a "contoso.com" bérlői tartomány. Ha tartalmazza, akkor kihagyja az e-mail-alapú felderítési folyamatot, amelyen a felhasználó végighalad a bejelentkezési oldalon, ami kissé leegyszerűsített felhasználói élményt eredményez. További információ az Auth Code Flow-dokumentumban és domain_hint dokumentumban elérhető lehetséges értékekről.

Alapértelmezett érték: None
max_age
int

SZABADON VÁLASZTHATÓ. Maximális hitelesítési életkor. A End-User aktív hitelesítésének utolsó időpontja óta eltelt időt adja meg másodpercekben. Ha az eltelt idő nagyobb ennél az értéknél, Microsoft Identitásplatform aktívan újra hitelesíti a végfelhasználót.

Az MSAL Python automatikusan ellenőrzi a auth_time azonosító jogkivonatban.

Az 1.15-ös verzió újdonságai.

Alapértelmezett érték: None
response_mode
str

SZABADON VÁLASZTHATÓ. Azt a metódust adja meg, amellyel a válaszparamétereket vissza kell adni. Az alapértelmezett érték megegyezik queryaz MSAL Python még mindig elég biztonságos értékével (mivel az MSAL Python nem ad át jogkivonatokat a lekérdezési paraméteren keresztül). A még jobb biztonság érdekében javasoljuk, hogy használja az értéket form_post. "form_post" módban a válaszparaméterek HTML-űrlapértékekként lesznek kódolva, amelyeket a HTTP POST metódussal továbbítunk, és a törzsbe kódolunk az alkalmazás/x-www-form-urlencoded formátum használatával. Az érvényes értékek lehetnek "form_post" a HTTP POST-hez az URI visszahívásához, vagy a HTTP GET esetében a lekérdezési sztringben kódolt paraméterekkel rendelkező "lekérdezés" (alapértelmezett). További információ a lehetséges értékekről itt https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes és itt https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html#FormPostResponseMode

Note

A webes keretrendszert úgy kell konfigurálnia, hogy lekérdezési válaszok helyett form_post válaszokat fogadjon el.

Bár ez a paraméter továbbra is működik, egy későbbi verzióban el lesz távolítva.

A lekérdezésalapú válaszmódok használata kevésbé biztonságos, ezért kerülni kell.

Alapértelmezett érték: None
claims_challenge
Alapértelmezett érték: None

Válaszok

Típus Description

A hitelesítési kód folyamata. Ez egy diktálás ebben a formában:


   {
       "auth_uri": "https://...",  // Guide user to visit this
       "state": "...",  // You may choose to verify it by yourself,
                        // or just let acquire_token_by_auth_code_flow()
                        // do that for you.
       "...": "...",  // Everything else are reserved and internal
   }

A hívónak a következőnek kell lennie:

  1. valahogy tárolja ezt a tartalmat, általában az aktuális munkamenetben,

  2. útmutatót a végfelhasználónak (azaz az erőforrás-tulajdonosnak) az adott auth_uri felkereséséhez,

  3. majd továbbadja a diktálást és az azt követő hitelesítési választ a következőnek acquire_token_by_auth_code_flow: .

is_pop_supported

Igaz értéket ad vissza, ha ez az ügyfél támogatja a birtoklás igazolása hozzáférési jogkivonatot.

is_pop_supported()

remove_account

Kijelentkeztetés és felejtés a tokengyorsítótárból

remove_account(account)

Paraméterek

Name Description
account
Kötelező

Attribútumok

ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID 

ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID = '832'

ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID 

ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID = '622'

ACQUIRE_TOKEN_BY_REFRESH_TOKEN 

ACQUIRE_TOKEN_BY_REFRESH_TOKEN = '85'

ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID 

ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID = '301'

ACQUIRE_TOKEN_FOR_CLIENT_ID 

ACQUIRE_TOKEN_FOR_CLIENT_ID = '730'

ACQUIRE_TOKEN_INTERACTIVE 

ACQUIRE_TOKEN_INTERACTIVE = '169'

ACQUIRE_TOKEN_ON_BEHALF_OF_ID 

ACQUIRE_TOKEN_ON_BEHALF_OF_ID = '523'

ACQUIRE_TOKEN_SILENT_ID 

ACQUIRE_TOKEN_SILENT_ID = '84'

ATTEMPT_REGION_DISCOVERY 

ATTEMPT_REGION_DISCOVERY = True

DISABLE_MSAL_FORCE_REGION 

DISABLE_MSAL_FORCE_REGION = False

GET_ACCOUNTS_ID 

GET_ACCOUNTS_ID = '902'

REMOVE_ACCOUNT_ID 

REMOVE_ACCOUNT_ID = '903'