ConfidentialClientApplication Sınıf

<xref:ClientApplication.__init__>parametresinin kalması Nonedışında allow_broker ile aynıdır.

Bir uygulama örneği oluşturun.

Oluşturucu

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)

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_for_client

Son kullanıcı için değil, geçerli gizli istemci için belirteç alır.

MSAL Python 1.23 olduğundan otomatik olarak önbellekten belirteç arar ve yalnızca önbellek yanıt vermediğinde Kimlik Sağlayıcısı'na istek gönderir.
acquire_token_on_behalf_of

Adına (OBO) akışı kullanarak belirteç alır.

Geçerli uygulama, son kullanıcıyı temsil eden bir belirteçle çağrılan bir orta katman hizmetidir. Geçerli uygulama, söz konusu kullanıcı adına aşağı akış web API'sine erişmek üzere başka bir belirteç istemek için bu tür bir belirteci (kullanıcı onayı) kullanabilir. Ayrıntılı belgelere buradan bakın.

Geçerli orta katman uygulamasının onay almak için kullanıcı etkileşimi yok. Bu makaleden orta katman uygulamanız için önceden onay almayı öğrenin. 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

Geçerli istemci için önceden aracılığıyla acquire_token_for_client alınan tüm belirteçleri kaldırın.

acquire_token_for_client

Son kullanıcı için değil, geçerli gizli istemci için belirteç alır.

MSAL Python 1.23 olduğundan otomatik olarak önbellekten belirteç arar ve yalnızca önbellek yanıt vermediğinde Kimlik Sağlayıcısı'na istek gönderir.

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

Parametreler

Name Description
scopes
Gerekli
list[str]

(Gerekli) 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
fmi_path
str

Optional. Federasyon Yönetilen Kimliği (FMI) kimlik bilgisi yolu. Sağlandığında, belirteç isteği gövdesinde parametre olarak fmi_path gönderilir ve sonuçta elde edilen belirteç ayrı olarak önbelleğe alınır, böylece farklı FMI yolları önbelleğe alınmış belirteçleri paylaşmaz. Örnek kullanım:


   result = cca.acquire_token_for_client(
       scopes=["api://resource/.default"],
       fmi_path="SomeFmiPath/FmiCredentialPath",
   )
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_on_behalf_of

Adına (OBO) akışı kullanarak belirteç alır.

Geçerli uygulama, son kullanıcıyı temsil eden bir belirteçle çağrılan bir orta katman hizmetidir. Geçerli uygulama, söz konusu kullanıcı adına aşağı akış web API'sine erişmek üzere başka bir belirteç istemek için bu tür bir belirteci (kullanıcı onayı) kullanabilir. Ayrıntılı belgelere buradan bakın.

Geçerli orta katman uygulamasının onay almak için kullanıcı etkileşimi yok. Bu makaleden orta katman uygulamanız için önceden onay almayı öğrenin. 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)

Parametreler

Name Description
user_assertion
Gerekli
str

Bu uygulama tarafından zaten alınan gelen belirteç
scopes
Gerekli
list[str]

Aşağı akış API'sinde (kaynak) gereken 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

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.

remove_tokens_for_client

Geçerli istemci için önceden aracılığıyla acquire_token_for_client alınan tüm belirteçleri kaldırın.

remove_tokens_for_client()