ClientApplication Klass

Din app har en client_id när du har registrerat den på Microsoft Entra administrationscenter.

För PublicClientApplicationanvänder du Ingen här.

För ConfidentialClientApplicationstöder den många olika indataformat för olika scenarier.

Stöd för användning av en klienthemlighet. Mata bara in en sträng, till exempel "your client secret".

Stöd för användning av ett certifikat i X.509-format (.pem)Deprecated eftersom det använder SHA-1 tumavtryck,

om du inte fortfarande använder ADFS som endast stöder SHA-1-tumavtryck. Använd pfx-alternativet som dokumenteras senare på den här sidan. Mata in i en diktamen i det här formuläret:

   {
       "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 kräver en "private_key" i PEM-format. Om certifikatet är i PKCS12-format (.pfx) kan du konvertera det till X.509-format (.pem) med openssl pkcs12 -in file.pfx -out file.pem -nodes. Tumavtrycket är tillgängligt i appens registrering i Azure Portal. Du kan också beräkna tumavtrycket. public_certificate (valfritt) är ett offentligt nyckelcertifikat som skickas via JWT-huvudet x5c. Detta är användbart när du använder autentisering med ämnesnamn/utfärdare , vilket är en metod för enklare certifikatrotation. Enligt specifikationerna är "certifikatet som innehåller den offentliga nyckeln som motsvarar nyckeln som används för att signera JWS digitalt det första certifikatet. Detta kan följas av ytterligare certifikat, där varje efterföljande certifikat är det som används för att certifiera det tidigare." Certifikatutfärdaren kan dock använda en annan ordning. Så om ditt försök får ett fel AADSTS700027 – "Det angivna signaturvärdet matchade inte det förväntade signaturvärdet" kan du försöka använda endast lövcertifikatet (i PEM/str-format) i stället.

Stöd för rå försäkran som erhållits från någon annanstanssom lagts till i version 1.13.0:

Det kan också vara en helt försignerad försäkran som du har sammanställt själv. Skicka bara en container som bara innehåller nyckeln "client_assertion", så här:

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

Stöd för läsning av klientcertifikat från PFX-filerDen här användningen använder automatiskt SHA-256-tumavtryck för certifikatet. Har lagts till i version 1.29.0:

Mata in i en ordlista som innehåller sökvägen till en PFX-fil:

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

Följande kommando genererar en .pfx-fil från din .key- och .pem-fil:

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

Ämnesnamn/utfärdarautentisering är en metod för att möjliggöra enklare certifikatrotation. Om pfx-filen innehåller både den privata nyckeln och det offentliga certifikatet kan du välja ämnesnamn/utfärdarautentisering genom att ange "public_certificate" till True.

Har lagts till i version 0.5.0: Det är en ordlista med extra anspråk som skulle signeras av den här ConfidentialClientApplication privata nyckeln. Du kan till exempel använda {"client_ip": "x.x.x.x"}. Du kan också åsidosätta något av följande standardanspråk:

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

En URL som identifierar en tokenutfärdare. Det bör vara av formatet https://login.microsoftonline.com/your_tenant Som standard använder vi https://login.microsoftonline.com/common

Har ändrats i version 1.17: Du kan också använda fördefinierad konstant och en byggare som den här:

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

(valfritt) Aktiverar eller inaktiverar verifiering av utfärdare. Den här parametern är som standard true.

Anger den tokencache som används av den här ClientApplication-instansen. Som standard skapas och används en minnesintern cache.

(valfritt) Din implementering av den abstrakta klassen HttpClient <msal.oauth2cli.http.http_client> Standardinställningar för en sessionsinstans för begäranden. Eftersom MSAL 1.11.0 konfigureras standardsessionen för att försöka utföra ett nytt försök med anslutningsfel. Om du tillhandahåller egna http_client är det din http_client skyldighet att bestämma om du vill göra ett nytt försök.

(valfritt) Den skickas till verifieringsparametern i biblioteket för underliggande begäranden Detta gäller inte om du har valt att skicka din egen Http-klient

(valfritt) Den skickas till proxyparametern i biblioteket för underliggande begäranden Detta gäller inte om du har valt att skicka din egen Http-klient

(valfritt) Den skickas till timeout-parametern i biblioteket för underliggande begäranden Detta gäller inte om du har valt att skicka din egen Http-klient

(valfritt) Du kan ange ditt programnamn för Microsoft telemetriändamål. Standardvärdet är Ingen, innebär att det inte skickas till Microsoft.

(valfritt) Du kan ange din programversion för Microsoft telemetriändamål. Standardvärdet är Ingen, innebär att det inte skickas till Microsoft.

(valfritt) Tillåter konfiguration av en eller flera klientfunktioner, t.ex. ["CP1"].

Klientfunktionen är avsedd att informera Microsofts identitetsplattform (STS) om vad den här klienten är kapabel till, så att STS kan välja att aktivera vissa funktioner. Om klienten till exempel kan hantera anspråksutmaningar kan STS utfärda CAE-åtkomsttoken (Continuous Access Evaluation) till resurser, med vetskapen om att klienten kommer att kunna hantera dessa utmaningar när resursen genererar en anspråksutmaning .

Implementeringsinformation: Klientfunktionen implementeras med hjälp av parametern "anspråk" på kabeln för tillfället. MSAL kombinerar dem i anspråksparametern som du senare anger via en av begäran om att hämta token.

(valfritt) Instruerar MSAL att använda entra regional token-tjänsten. Den här äldre funktionen är endast tillgänglig för program från första part. Endast acquire_token_for_client() stöds.

Stöder 4 värden:

1. azure_region=None – Det här standardvärdet innebär att ingen region har konfigurerats. MSAL använder den region som definierats i env var MSAL_FORCE_REGION.

2. azure_region="some_region" – vilket innebär att den angivna regionen används.

3. azure_region=True – vilket innebär att MSAL försöker identifiera regionen automatiskt. Detta rekommenderas inte.

4. azure_region=False – vilket innebär att MSAL inte använder någon region.

Ny i version 1.12.0.

(valfritt) Tidigare har MSAL-hårdkoder offline_access omfång, vilket skulle göra det möjligt för din app att ha långvarig åtkomst till användarens data. Om det är onödigt eller oönskat för din app kan du nu använda den här parametern för att ange en undantagslista med omfång, till exempel exclude_scopes = ["offline_access"].

MSAL har länge cachelagra token i token_cache. Nyligen introducerade MSAL också ett koncept för http_cache, genom att automatiskt cachelagra en viss begränsad mängd http-svar som inte är token, så att långlivadePublicClientApplication och ConfidentialClientApplication skulle vara mer högpresterande och dynamiska i vissa situationer.

Den här http_cache parametern accepterar valfritt diktatörsliknande objekt. Om det inte anges använder MSAL en minnesintern diktering.

Om din app är en kommandoradsapp (CLI) vill du spara dina http_cache mellan olika CLI-körningar. Den bevarade filens format kan ändras på grund av, men inte begränsat till, instabilt protokoll, så implementeringen tolererar oväntade inläsningsfel. Följande recept visar ett sätt att göra det:

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

Innehållet inuti http_cache är billigt att få. Du behöver inte dela dem mellan olika appar.

Innehållet inuti http_cache innehåller inga token eller personligt identifierbar information (PII). Kryptering är onödigt.

Nytt i version 1.16.0.

Tidigare skulle MSAL ansluta till en central slutpunkt som finns vid https://login.microsoftonline.com för att hämta vissa metadata, särskilt när du använder en okänd auktoritet. Det här beteendet kallas instansidentifiering.

Den här parametern är som standard Ingen, vilket aktiverar instansidentifieringen.

Om du känner till vissa myndigheter som du tillåter msal att arbeta med as-is, utan att ta med någon instansidentifiering, är det rekommenderade mönstret:

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

Om du inte känner till vissa myndigheter i förväg, men ändå vill att MSAL ska godkänna alla utfärdare som du anger, kan du använda en False för att ovillkorligt inaktivera identifiering av instanser.

Nytt i version 1.19.0.

Deprecated. Använd enable_broker_on_windows i stället.

När det är aktiverat kan loggarna innehålla PII (personlig identifierbar information). Detta kan vara användbart vid felsökning av koordinatorbeteenden. Standardbeteendet är False.

Nytt i version 1.24.0.

Har lagts till i version 1.28.0: Det är en URL som identifierar en OpenID Connect-utfärdare (OIDC) i formatet https://contoso.com/tenant. MSAL lägger till ".well-known/openid-configuration" till utfärdaren och hämtar OIDC-metadata därifrån för att ta reda på slutpunkterna.

Obs! Broker används INTE för OIDC-utfärdare.