ClientApplication Sınıf

Genellikle bu sınıfı doğrudan kullanmazsınız. Bunun yerine alt sınıflarını kullanın: PublicClientApplication ve ConfidentialClientApplication.

Bir uygulama örneği oluşturun.

Oluşturucu

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)

Parametreler

Name Description
client_id
Gerekli
str

Uygulamanızın Microsoft Entra yönetim merkezi kaydettikten sonra bir client_id vardır.
client_credential
Union[dict, str, None]

için PublicClientApplicationburada None kullanırsınız.

için ConfidentialClientApplication, farklı senaryolar için birçok farklı giriş biçimi destekler.

İstemci gizli dizisi kullanma desteği. Yalnızca gibi "your client secret"bir dizede besleyin.

SHA-1 parmak izi kullandığından X.509 (.pem) biçiminde sertifika kullanma desteğiKönemli

yalnızca SHA-1 parmak izini destekleyen ADFS kullanmaya devam etmediğiniz sürece. Lütfen bu sayfanın ilerleyen bölümlerinde belgelenen .pfx seçeneğini kullanın. Bu formdaki bir dikte besleyin:


   {
       "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 PEM biçiminde bir "private_key" gerektirir. Sertifikanız PKCS12 (.pfx) biçimindeyse, tarafından X.509 (.pem) biçimine openssl pkcs12 -in file.pfx -out file.pem -nodesdönüştürebilirsiniz. Parmak izi, uygulamanızın Azure portal kaydında kullanılabilir. Alternatif olarak parmak izini hesaplayabilirsiniz. public_certificate (isteğe bağlı), 'x5c' JWT üst bilgisi aracılığıyla gönderilecek ortak anahtar sertifikasıdır. Bu, daha kolay sertifika döndürmeye izin veren bir yaklaşım olan Konu Adı/Veren Kimlik Doğrulaması kullandığınızda kullanışlıdır. Belirtimlere göre, "JWS'yi dijital olarak imzalamak için kullanılan anahtara karşılık gelen ortak anahtarı içeren sertifika ilk sertifika OLMALıDıR. Bu, sonraki her sertifikanın önceki sertifikayı onaylamak için kullanılan sertifika olmasıyla birlikte ek sertifikalar tarafından takip edilebilir." Ancak sertifikanızın vereni farklı bir sipariş kullanabilir. Bu nedenle, denemeniz "Sağlanan imza değeri beklenen imza değeriyle eşleşmedi" hatasını AADSTS700027, bunun yerine yalnızca yaprak sertifikasını (PEM/str biçiminde) kullanmayı deneyebilirsiniz.

Başka bir yerden alınan ham onaylamayı desteklemeSürüm 1.13.0'da eklendi:

Ayrıca, kendi oluşturduğunuz tamamen önceden imzalanmış bir onay da olabilir. Yalnızca "client_assertion" anahtarını içeren bir kapsayıcıyı geçirmeniz yeterlidir, örneğin:


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

PFX dosyalarından istemci sertifikalarının okunmasını desteklemeBu kullanım otomatik olarak sertifikanın SHA-256 parmak izini kullanır. Sürüm 1.29.0'da eklendi:

PFX dosyasının yolunu içeren bir sözlükte akış:


   {
       "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şağıdaki komut, .key ve .pem dosyanızdan bir .pfx dosyası oluşturur:


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

Konu Adı/Veren Kimlik Doğrulaması , daha kolay sertifika döndürmeye olanak sağlayan bir yaklaşımdır. .pfx dosyanız hem özel anahtarı hem de ortak sertifikayı içeriyorsa, "public_certificate" Trueayarını olarak ayarlayarak Konu Adı/Veren Kimlik Doğrulaması'nı kabul edebilirsiniz.

Default value: None
client_claims
dict

Sürüm 0.5.0'da eklendi: Bu, bu ConfidentialClientApplication 'nin özel anahtarı tarafından imzalanacak ek talepler sözlüğüdür. Örneğin, {"client_ip": "x.x.x.x"} kullanabilirsiniz. Aşağıdaki varsayılan taleplerden herhangi birini de geçersiz kılabilirsiniz:


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

Belirteç yetkilisini tanımlayan bir URL. Bu biçimde olmalıdır https://login.microsoftonline.com/your_tenant Varsayılan olarak https://login.microsoftonline.com/common

Sürüm 1.17'de değiştirildi: Önceden tanımlanmış sabiti ve aşağıdaki gibi bir oluşturucuyu da kullanabilirsiniz:


   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, ...)
Default value: None
validate_authority
bool

(isteğe bağlı) Yetkili doğrulamayı açar veya kapatır. Bu parametre varsayılan olarak true olarak ayarlanır.

Default value: True
token_cache
TokenCache

Bu ClientApplication örneği tarafından kullanılan belirteç önbelleğini ayarlar. Varsayılan olarak, bellek içi önbellek oluşturulur ve kullanılır.

Default value: None
http_client

(isteğe bağlı) HttpClient <msal.oauth2cli.http.http_client> soyut sınıfı uygulamanız bir istekler oturumu örneğine varsayılan olarak uygulanır. MSAL 1.11.0'dan bu yana, varsayılan oturum bağlantı hatasında bir yeniden deneme deneyecek şekilde yapılandırılır. Kendi http_client sağlıyorsanız, yeniden deneme yapıp yapmamaya karar vermek http_client göreviniz olacaktır.

Default value: None
verify

(isteğe bağlı) Temel istekler kitaplığındaki verify parametresine geçirilir Bu, kendi Http istemcinizi geçirmeyi seçtiyseniz geçerli değildir

Default value: True
proxies

(isteğe bağlı) Temel istekler kitaplığındaki proxy'ler parametresine geçirilir Bu, kendi Http istemcinizi geçirmeyi seçtiyseniz geçerli değildir

Default value: None
timeout

(isteğe bağlı) Temel istekler kitaplığındaki zaman aşımı parametresine geçirilir Bu, kendi Http istemcinizi geçirmeyi seçtiyseniz geçerli değildir

Default value: None
app_name

(isteğe bağlı) Uygulama adınızı Microsoft telemetri amacıyla sağlayabilirsiniz. Varsayılan değer Yok değeridir, Microsoft geçirilmeyecek anlamına gelir.

Default value: None
app_version

(isteğe bağlı) Uygulama sürümünüzü Microsoft telemetri amacıyla sağlayabilirsiniz. Varsayılan değer Yok değeridir, Microsoft geçirilmeyecek anlamına gelir.

Default value: None
client_capabilities
list[str]

(isteğe bağlı) ["CP1"] gibi bir veya daha fazla istemci özelliği yapılandırmaya izin verir.

İstemci özelliğinin amacı, Microsoft kimlik platformu (STS) bu istemcinin neler yapabileceğini bildirmektir, böylece STS belirli özellikleri etkinleştirmeye karar verebilir. Örneğin, istemci talep sınamasını işleyebiliyorsa, STS kaynaklara Sürekli Erişim Değerlendirmesi (CAE) erişim belirteçleri verebilir ve kaynak bir talep yaydığında istemcinin bu zorlukların üstesinden gelebileceğini bilir.

Uygulama ayrıntıları: İstemci özelliği şimdilik kabloda "claims" parametresi kullanılarak uygulanır. MSAL, bunları daha sonra alma belirteci isteğinden biri aracılığıyla sağlayacağınız talep parametresinde birleştirir.

Default value: None
azure_region
str

(isteğe bağlı) MSAL'ye Entra bölgesel belirteç hizmetini kullanmasını sağlar. Bu eski özellik yalnızca birinci taraf uygulamalar tarafından kullanılabilir. Yalnızca acquire_token_for_client() desteklenir.

4 değeri destekler:

  1. azure_region=None - Bu varsayılan değer, hiçbir bölgenin yapılandırılmadığını gösterir. MSAL, env var MSAL_FORCE_REGIONiçinde tanımlanan bölgeyi kullanır.

  2. azure_region="some_region" - belirtilen bölgenin kullanıldığı anlamına gelir.

  3. azure_region=True - MSAL'nin bölgeyi otomatik olarak algılamaya çalışacağı anlamına gelir. Bu önerilmez.

  4. azure_region=False - MSAL'nin bölge kullanmayacağı anlamına gelir.

Note

Bölge otomatik bulma vm'lerde ve Azure İşlevleri üzerinde test edilmiştir. Güvenilir değil.

Bu seçeneği kullanan uygulamalar kısa bir zaman aşımı yapılandırmalıdır.

Daha fazla ayrıntı ve bölge dizesinin değerleri için

bkz. https://learn.microsoft.com/entra/msal/dotnet/resources/region-discovery-troubleshooting

Sürüm 1.12.0'da yeni.

Default value: None
exclude_scopes
list[str]

(isteğe bağlı) Geçmişte MSAL sabit kodları , uygulamanızın kullanıcının verilerine uzun süre erişmesini sağlayacak offline_access kapsam oluşturur. Bu, uygulamanız için gereksiz veya istenmeyen bir durumsa, artık gibi exclude_scopes = ["offline_access"]kapsamların dışlama listesini sağlamak için bu parametreyi kullanabilirsiniz.

Default value: None
http_cache
dict

MSAL uzun süredir içinde token_cachebelirteçleri önbelleğe almıştır. MSAL, kısa süre önce, uzun ömürlüPublicClientApplication ve bazı durumlarda daha yüksek performanslı ve ConfidentialClientApplication duyarlı olması için belirli sayıda belirteç olmayan http yanıtını otomatik olarak önbelleğe alarak bir kavramı http_cacheda kullanıma sunulmuştur.

Bu http_cache parametre dikte benzeri herhangi bir nesneyi kabul eder. Sağlanmazsa, MSAL bellek içi bir dikte kullanır.

Uygulamanız bir komut satırı uygulaması (CLI) ise, http_cache farklı CLI çalıştırmaları arasında kalıcı hale getirmek isteyebilirsiniz. Kalıcı dosyanın biçimi kararsız protokol nedeniyle değişebilir ancak bunlarla sınırlı olmamak üzere, uygulamanız beklenmeyen yükleme hatalarına tolerans gösterecektir. Aşağıdaki tarif bunu yapmak için bir yol gösterir:


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

İçindeki http_cache içerik elde etmek ucuz. Bunları farklı uygulamalar arasında paylaşmanıza gerek yoktur.

İçindeki http_cache içerik hiçbir belirteç veya Kişisel Bilgi (PII) içermez. Şifreleme gereksizdir.

Sürüm 1.16.0'da yeni.

Default value: None
instance_discovery
<xref:boolean>

Geçmişte MSAL, özellikle de tanıdık olmayan bir yetkili kullanırken bazı meta verileri almak için konumunda https://login.microsoftonline.com bulunan merkezi bir uç noktaya bağlanırdı. Bu davranış Örnek Bulma olarak bilinir.

Bu parametre varsayılan olarak Yok olarak ayarlıdır ve Örnek Bulma'yı etkinleştirir.

MSAL'nin as-isile herhangi bir Örnek Bulma içermeden çalışmasına izin veren bazı yetkilileri biliyorsanız, önerilen düzen şunlardır:


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

Bazı yetkilileri önceden tanımıyorsanız ancak yine de MSAL'nin sağlayacağınız herhangi bir yetkiyi kabul etmelerini istiyorsanız, Örnek Bulma'yı koşulsuz olarak devre dışı bırakmak için bir False kullanabilirsiniz.

Sürüm 1.19.0'da yeni.

Default value: None
allow_broker
<xref:boolean>

Deprecated. Bunun yerine lütfen kullanın enable_broker_on_windows .

Default value: None
enable_pii_log
<xref:boolean>

Etkinleştirildiğinde günlükler PII (Kişisel Olarak Tanımlanabilir Bilgiler) içerebilir. Bu, aracı davranışlarını gidermede yararlı olabilir. Varsayılan davranış False'tur.

Sürüm 1.24.0'da yeni.

Default value: None
oidc_authority
str

Sürüm 1.28.0'da eklendi: Biçiminin https://contoso.com/tenantOpenID Connect (OIDC) yetkilisini tanımlayan bir URL'dir. MSAL, yetkiliye ".well-known/openid-configuration" ekler ve uç noktaları bulmak için OIDC meta verilerini oradan alır.

Not: Aracı, OIDC yetkilisi için KULLANILMAYACAKTIR.

Default value: None

Yöntemler

acquire_token_by_auth_code_flow

Yeniden yönlendirilmekte olan kimlik doğrulama yanıtını doğrulayın ve belirteçleri alın.

Otomatik olarak nonce koruması sağlar.
acquire_token_by_authorization_code

Yetkilendirme Kodu Verme işleminin ikinci yarısı.
acquire_token_by_refresh_token

Başka bir yerden alınan yenileme belirtecini (RT) temel alarak belirteçleri alma.

Bu yöntemi yalnızca başka bir yerden eski RT'leriniz varsa ve şimdi bunları MSAL'ye geçirmek istediğinizde kullanırsınız. Bu yöntemin çağrılması, yeni belirteçlerin otomatik olarak MSAL'da depolanmasına neden olur.

Zaten MSAL kullanıyorsanız bu yöntemi kullanmanız GEREKMEZ. MSAL, RT'yi belirteç önbelleğinde otomatik olarak tutar ve çağırdığınızda acquire_token_silenterişim belirteci alınabilir.
acquire_token_by_username_password

Kullanıcı kimlik bilgileri aracılığıyla belirli bir kaynak için belirteç alır.

Kullanıcı Adı Parola Akışı kısıtlamaları için bu sayfaya bakın. https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication

[Kullanım dışı] Bu API, genel istemci akışları için kullanım dışıdır ve gelecekteki bir sürümde kaldırılacaktır. Bunun yerine daha güvenli bir akış kullanın. Geçiş kılavuzu: https://aka.ms/msal-ropc-migration
acquire_token_silent

Kullanıcı etkileşimi olmadan belirli bir hesap için erişim belirteci alma.

ile aynı parametrelere acquire_token_silent_with_errorsahiptir. Fark, dönüş değerinin davranışıdır. Bu yöntem önbellek boş ve yenileme hatasını tek bir dönüş değeri olan Hiçbiri olarak birleştirir. Uygulamanız, belirteç önbelleği arama sırasında tam belirteç yenileme hatasıyla ilgilenmiyorsa, bu yöntem daha kolay ve önerilir.
acquire_token_silent_with_error

Kullanıcı etkileşimi olmadan belirli bir hesap için erişim belirteci alma.

Önbellekten geçerli bir erişim belirteci bulunarak veya önbellekten geçerli bir yenileme belirteci bulunarak yapılır ve ardından yeni erişim belirtecini kullanmak için otomatik olarak kullanılır.

Bu yöntem, boş önbelleği belirteç yenileme hatasından ayırt eder. Uygulamanız belirteç önbelleği arama sırasında tam belirteç yenileme hatasını önemsiyorsa, bu yöntem uygundur. Aksi takdirde, diğer yöntem acquire_token_silent önerilir.
get_accounts

Daha önce oturum açmış hesapların listesini alın; örneğin önbellekte var.

Bir hesap daha sonra belirteçlerini bulmak için içinde acquire_token_silent kullanılabilir.
get_authorization_request_url

Yetkilendirme Kodu Verme işlemini başlatmanız için bir URL oluşturur.
initiate_auth_code_flow

Kimlik doğrulama kodu akışı başlatın.

Yanıt daha sonra redirect_uri ulaştığında, kimlik doğrulamasını/yetkilendirmeyi tamamlamak için kullanabilirsiniz acquire_token_by_auth_code_flow .
is_pop_supported

Bu istemci SahipLik Kanıtı Erişim Belirtecini destekliyorsa True döndürür.
remove_account

Oturumu kapatma ve belirteç önbelleğinde beni unutma

acquire_token_by_auth_code_flow

Yeniden yönlendirilmekte olan kimlik doğrulama yanıtını doğrulayın ve belirteçleri alın.

Otomatik olarak nonce koruması sağlar.

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

Parametreler

Name Description
auth_code_flow
Gerekli
dict

tarafından initiate_auth_code_flowdöndürülen aynı dikte.
auth_response
Gerekli
dict

Kimlik doğrulama sunucusundan alınan sorgu dizesinin bir diktesi.
scopes
list[str]

Korumalı API'ye (kaynak) erişmek için istenen kapsamlar.

Çoğu zaman boş bırakabilirsiniz.

Birden çok kaynak için kullanıcı onayı istediyseniz, burada içinde initiate_auth_code_flowgerekenlerin bir alt kümesini sağlamanız gerekir.

OAuth2 çoğunlukla tekil hizmetler için tasarlanmıştır; burada belirteçler her zaman aynı kaynak için tasarlanmıştır ve tek değişiklikler kapsamlardadır. Microsoft Entra'da, birden çok üçüncü taraf kaynağı için belirteçler oluşturulabilir. Birden çok kaynak için yetkilendirme kodu isteyebilirsiniz, ancak bunu kullandığınızda belirteç hedeflenen bir alıcıya (hedef kitle olarak adlandırılır) yöneliktir. Bu nedenle geliştiricinin belirteci ilgili hedef kitle için verilmek üzere kısıtlayabilmemiz için bir kapsam belirtmesi gerekir.

Default value: None

Döndürülenler

Tür Description

  • "access_token" ve/veya "id_token" içeren bir dikte, hangi kapsamın kullanıldığına bağlıdır. (Bkz. https://tools.ietf.org/html/rfc6749#section-5.1)

  • "error", isteğe bağlı olarak "error_description", "error_uri" içeren bir dikte. (Bu veya bu)

  • çoğu istemci tarafı veri hatası ValueError özel durumuyla sonuçlanır. Bu nedenle kullanım düzeni herhangi bir protokol ayrıntısı olmadan olabilir:

    
   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

Yetkilendirme Kodu Verme işleminin ikinci yarısı.

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

Parametreler

Name Description
code
Gerekli

Yetkilendirme Sunucusundan döndürülen yetkilendirme kodu.
scopes
Gerekli
list[str]

(Gerekli) Korumalı API'ye (kaynak) erişmek için istenen kapsamlar.

Birden çok kaynak için kullanıcı onayı istediyseniz, burada genellikle AuthCode'da gerekenlerin bir alt kümesini sağlamak istersiniz.

OAuth2 çoğunlukla tekil hizmetler için tasarlanmıştır; burada belirteçler her zaman aynı kaynak için tasarlanmıştır ve tek değişiklikler kapsamlardadır. Microsoft Entra'de, birden çok üçüncü taraf kaynağı için belirteçler oluşturulabilir. Birden çok kaynak için yetkilendirme kodu isteyebilirsiniz, ancak bunu kullandığınızda belirteç hedeflenen bir alıcıya (hedef kitle olarak adlandırılır) yöneliktir. Bu nedenle geliştiricinin belirteci ilgili hedef kitle için verilmek üzere kısıtlayabilmemiz için bir kapsam belirtmesi gerekir.
nonce

çağrısı get_authorization_request_urlyaparken bir nonce sağladıysanız, doğrulamamız için burada da aynı nonce sağlanmalıdır. Kimlik belirtecindeki nonce uyuşmazlıkları durumunda bir özel durum oluşturulur.

Default value: None
claims_challenge

claims_challenge parametresi, kaynak sağlayıcısı tarafından www-authenticate üst bilgisindeki bir claims_challenge yönergesi biçiminde istenen belirli talepleri UserInfo Uç Noktasından ve/veya Kimlik Belirteci ve/veya Erişim Belirteci'nden döndürülmek üzere ister. Bu, bu konumlardan istenen talep listelerini içeren bir JSON nesnesinin dizesidir.

Default value: None
redirect_uri
Default value: None

Döndürülenler

Tür Description

Microsoft Entra json yanıtını temsil eden bir dikte:

  • Başarılı bir yanıt "access_token" anahtarı içerebilir,

  • bir hata yanıtı "hata" ve genellikle "error_description" içerebilir.

acquire_token_by_refresh_token

Başka bir yerden alınan yenileme belirtecini (RT) temel alarak belirteçleri alma.

Bu yöntemi yalnızca başka bir yerden eski RT'leriniz varsa ve şimdi bunları MSAL'ye geçirmek istediğinizde kullanırsınız. Bu yöntemin çağrılması, yeni belirteçlerin otomatik olarak MSAL'da depolanmasına neden olur.

Zaten MSAL kullanıyorsanız bu yöntemi kullanmanız GEREKMEZ. MSAL, RT'yi belirteç önbelleğinde otomatik olarak tutar ve çağırdığınızda acquire_token_silenterişim belirteci alınabilir.

acquire_token_by_refresh_token(refresh_token, scopes, **kwargs)

Parametreler

Name Description
refresh_token
Gerekli
str

Dize olarak eski yenileme belirteci.
scopes
Gerekli
list

Kapsamlar bu eski RT ile ilişkilendirildi. Her kapsamın Microsoft kimlik platformu (v2) biçiminde olması gerekir. Bkz. Kaynaklar değil kapsamlar.

Döndürülenler

Tür Description

  • Hata oluştuğunda bir dikte "error" ve diğer bazı anahtarlar bulunur.

  • Bir dikte "hata" anahtarı yok, geçişin başarılı olduğu anlamına gelir.

acquire_token_by_username_password

Kullanıcı kimlik bilgileri aracılığıyla belirli bir kaynak için belirteç alır.

Kullanıcı Adı Parola Akışı kısıtlamaları için bu sayfaya bakın. https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication

[Kullanım dışı] Bu API, genel istemci akışları için kullanım dışıdır ve gelecekteki bir sürümde kaldırılacaktır. Bunun yerine daha güvenli bir akış kullanın. Geçiş kılavuzu: https://aka.ms/msal-ropc-migration

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

Parametreler

Name Description
username
Gerekli
str

Genellikle e-posta adresi biçiminde bir UPN.
password
Gerekli
str

Parola.
scopes
Gerekli
list[str]

Korumalı API'ye (kaynak) erişmek için istenen kapsamlar.
claims_challenge

claims_challenge parametresi, kaynak sağlayıcısı tarafından www-authenticate üst bilgisindeki bir claims_challenge yönergesi biçiminde istenen belirli talepleri UserInfo Uç Noktasından ve/veya Kimlik Belirteci ve/veya Erişim Belirteci'nden döndürülmek üzere ister. Bu, bu konumlardan istenen talep listelerini içeren bir JSON nesnesinin dizesidir.

Default value: None
auth_scheme
object

MSAL'nin sizin için bir Sahiplik Kanıtı (POP) belirteci alması için bir nesne sağlayabilirsiniz msal.auth_scheme.PopAuthScheme .

Sürüm 1.26.0'da yeni.

Default value: None

Döndürülenler

Tür Description

Microsoft Entra json yanıtını temsil eden bir dikte:

  • Başarılı bir yanıt "access_token" anahtarı içerebilir,

  • bir hata yanıtı "hata" ve genellikle "error_description" içerebilir.

acquire_token_silent

Kullanıcı etkileşimi olmadan belirli bir hesap için erişim belirteci alma.

ile aynı parametrelere acquire_token_silent_with_errorsahiptir. Fark, dönüş değerinin davranışıdır. Bu yöntem önbellek boş ve yenileme hatasını tek bir dönüş değeri olan Hiçbiri olarak birleştirir. Uygulamanız, belirteç önbelleği arama sırasında tam belirteç yenileme hatasıyla ilgilenmiyorsa, bu yöntem daha kolay ve önerilir.

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

Parametreler

Name Description
scopes
Gerekli
account
Gerekli
authority
Default value: None
force_refresh
Default value: False
claims_challenge
Default value: None
auth_scheme
Default value: None

Döndürülenler

Tür Description

  • Önbellek araması başarılı olursa " hata" anahtarı içermeyen ve genellikle bir "access_token" anahtarı içeren bir dikte.

  • Önbellek araması bir belirteç sağlamadığında hiçbiri.

acquire_token_silent_with_error

Kullanıcı etkileşimi olmadan belirli bir hesap için erişim belirteci alma.

Önbellekten geçerli bir erişim belirteci bulunarak veya önbellekten geçerli bir yenileme belirteci bulunarak yapılır ve ardından yeni erişim belirtecini kullanmak için otomatik olarak kullanılır.

Bu yöntem, boş önbelleği belirteç yenileme hatasından ayırt eder. Uygulamanız belirteç önbelleği arama sırasında tam belirteç yenileme hatasını önemsiyorsa, bu yöntem uygundur. Aksi takdirde, diğer yöntem acquire_token_silent önerilir.

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

Parametreler

Name Description
scopes
Gerekli
list[str]

(Gerekli) Korumalı API'ye (kaynak) erişmek için istenen kapsamlar.
account
Gerekli

(Gerekli) tarafından get_accountsdöndürülen hesap nesnelerinden biri. MSAL Python 1.23'ten başlayarak, giriş None bir NO-OP olur ve her zaman döndürürNone.
force_refresh

True ise, Erişim Belirteci aramasını atlar ve yeni bir Erişim Belirteci almak için Bir Yenileme Belirteci bulmaya çalışır.

Default value: False
claims_challenge

claims_challenge parametresi, kaynak sağlayıcısı tarafından www-authenticate üst bilgisindeki bir claims_challenge yönergesi biçiminde istenen belirli talepleri UserInfo Uç Noktasından ve/veya Kimlik Belirteci ve/veya Erişim Belirteci'nden döndürülmek üzere ister. Bu, bu konumlardan istenen talep listelerini içeren bir JSON nesnesinin dizesidir.

Default value: None
auth_scheme
object

MSAL'nin sizin için bir Sahiplik Kanıtı (POP) belirteci alması için bir nesne sağlayabilirsiniz msal.auth_scheme.PopAuthScheme .

Sürüm 1.26.0'da yeni.

Default value: None
authority
Default value: None

Döndürülenler

Tür Description

  • Önbellek araması başarılı olursa " hata" anahtarı içermeyen ve genellikle bir "access_token" anahtarı içeren bir dikte.

  • Önbellekte yalnızca belirteç olmadığında hiçbiri.

  • Belirteç yenileme başarısız olduğunda "hata" anahtarı içeren bir dikte.

get_accounts

Daha önce oturum açmış hesapların listesini alın; örneğin önbellekte var.

Bir hesap daha sonra belirteçlerini bulmak için içinde acquire_token_silent kullanılabilir.

get_accounts(username=None)

Parametreler

Name Description
username

Hesapları yalnızca bu kullanıcı adıyla filtreleyin. Büyük/küçük harfe duyarsız.

Default value: None

Döndürülenler

Tür Description

Hesap nesnelerinin listesi. Her hesap bir diktedir. Şimdilik yalnızca "kullanıcı adı" alanını belgeleyeceğiz. Uygulamanız bu bilgileri son kullanıcıya görüntülemeyi seçebilir ve devam etmek için kullanıcının kendi hesaplarından birini seçmesine izin verebilir.

get_authorization_request_url

Yetkilendirme Kodu Verme işlemini başlatmanız için bir URL oluşturur.

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)

Parametreler

Name Description
scopes
Gerekli
list[str]

(Gerekli) Korumalı API'ye (kaynak) erişmek için istenen kapsamlar.
state
str

CSRF koruması için OAuth2 tarafından önerilir.

Default value: None
login_hint
str

Kullanıcının tanımlayıcısı. Genellikle kullanıcı asıl adı (UPN).

Default value: None
redirect_uri
str

Yetkiliden bir yanıt aldıktan sonra geri dönülecek adres.

Default value: None
response_type
str

OAuth2 Yetkilendirme Kodu verme işlemi için varsayılan değer "koddur".

"id_token" veya "belirteç" gibi diğer içerikleri kullanabilirsiniz. Bu içerik Örtük Bir Verme işlemi tetikleyebilir, ancak bu önerilmez.

Default value: code
prompt
str

Varsayılan olarak, dize "none"bile değil, hiçbir istem değeri gönderilmez. Açıkça bir değer belirtmeniz gerekir. Geçerli değerleri içinde <xref:msal.Prompt>tanımlanan sabitlerdir.

Default value: None
nonce

Yeniden yürütme saldırılarını azaltmak için kullanılan kriptografik rastgele bir değer. Ayrıca bkz . OIDC özellikleri.

Default value: None
domain_hint

"Tüketiciler" veya "kuruluşlar" ya da kiracı etki alanınız "contoso.com" olabilir. Dahil edilirse, kullanıcının oturum açma sayfasından geçtiği e-posta tabanlı bulma işlemini atlar ve bu da biraz daha kolay bir kullanıcı deneyimine yol açar. Kimlik Doğrulama Kodu Akışı belgesinde ve domain_hint belgesinde bulunan olası değerler hakkında daha fazla bilgi.

Default value: None
claims_challenge

claims_challenge parametresi, kaynak sağlayıcısı tarafından www-authenticate üst bilgisindeki bir claims_challenge yönergesi biçiminde istenen belirli talepleri UserInfo Uç Noktasından ve/veya Kimlik Belirteci ve/veya Erişim Belirteci'nden döndürülmek üzere ister. Bu, bu konumlardan istenen talep listelerini içeren bir JSON nesnesinin dizesidir.

Default value: None

Döndürülenler

Tür Description

Dize olarak yetkilendirme URL'si.

initiate_auth_code_flow

Kimlik doğrulama kodu akışı başlatın.

Yanıt daha sonra redirect_uri ulaştığında, kimlik doğrulamasını/yetkilendirmeyi tamamlamak için kullanabilirsiniz acquire_token_by_auth_code_flow .

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)

Parametreler

Name Description
scopes
Gerekli
list

Büyük/küçük harfe duyarlı dizelerin listesidir.
redirect_uri
str

Optional. Belirtilmezse, sunucu önceden kaydedilmiş olanı kullanır.

Default value: None
state
str

İstek ve geri çağırma arasında durumu korumak için istemci tarafından kullanılan opak bir değer. Yoksa, bu kitaplık otomatik olarak dahili olarak bir kitaplık oluşturur.

Default value: None
prompt
str

Varsayılan olarak, dize "none"bile değil, hiçbir istem değeri gönderilmez. Açıkça bir değer belirtmeniz gerekir. Geçerli değerleri içinde <xref:msal.Prompt>tanımlanan sabitlerdir.

Default value: None
login_hint
str

Optional. Kullanıcının tanımlayıcısı. Genellikle kullanıcı asıl adı (UPN).

Default value: None
domain_hint

"Tüketiciler" veya "kuruluşlar" ya da kiracı etki alanınız "contoso.com" olabilir. Dahil edilirse, kullanıcının oturum açma sayfasından geçtiği e-posta tabanlı bulma işlemini atlar ve bu da biraz daha kolay bir kullanıcı deneyimine yol açar. Kimlik Doğrulama Kodu Akışı belgesinde ve domain_hint belgesinde bulunan olası değerler hakkında daha fazla bilgi.

Default value: None
max_age
int

OPSİYONEL. En Fazla Kimlik Doğrulama Yaşı. End-User etkin bir şekilde kimliğinin doğrulandığı son zamandan bu yana izin verilebilen süreyi saniye cinsinden belirtir. Geçen süre bu değerden büyükse, Microsoft kimlik platformu son kullanıcının kimliğini etkin bir şekilde yeniden doğrular.

MSAL Python ayrıca kimlik belirtecindeki auth_time otomatik olarak doğrular.

Sürüm 1.15'te yeni.

Default value: None
response_mode
str

OPSİYONEL. Yanıt parametrelerinin döndürülmesi gereken yöntemi belirtir. Varsayılan değer, MSAL Python yeterince güvenli olan değerine eşdeğerdir query(çünkü MSAL Python ilk etapta belirteçleri sorgu parametresi aracılığıyla aktarmaz). Daha da iyi güvenlik için değerini form_postkullanmanızı öneririz. "form_post" modunda, yanıt parametreleri HTTP POST yöntemi aracılığıyla iletilen ve uygulama/x-www-form-urlencoded biçimi kullanılarak gövdede kodlanan HTML form değerleri olarak kodlanır. Geçerli değerler, HTTP POST için geri çağırma URI'si için "form_post" veya sorgu dizesinde kodlanmış parametrelerle HTTP GET için "sorgu" (varsayılan) olabilir. Burada https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes ve burada https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html#FormPostResponseMode olası değerler hakkında daha fazla bilgi

Note

Web çerçevenizi sorgu yanıtları yerine form_post yanıtları kabul etmek üzere yapılandırmanız gerekir.

Bu parametre çalışmaya devam ederken, gelecekteki bir sürümde kaldırılacaktır.

Sorgu tabanlı yanıt modlarını kullanmak daha az güvenlidir ve bundan kaçınılmalıdır.

Default value: None
claims_challenge
Default value: None

Döndürülenler

Tür Description

Kimlik doğrulama kodu akışı. Bu biçimdeki bir diktedir:


   {
       "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ğıranın şu şekilde olması beklenir:

  1. bir şekilde bu içeriği, genellikle geçerli oturumun içinde depolayın

  2. bu auth_uri ziyaret etmek için son kullanıcıya (örneğin kaynak sahibi) rehberlik edin,

  3. ve ardından bu dikte ve sonraki kimlik doğrulama yanıtlarını öğesine geçirin acquire_token_by_auth_code_flow.

is_pop_supported

Bu istemci SahipLik Kanıtı Erişim Belirtecini destekliyorsa True döndürür.

is_pop_supported()

remove_account

Oturumu kapatma ve belirteç önbelleğinde beni unutma

remove_account(account)

Parametreler

Name Description
account
Gerekli

Öznitelikler

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'