ClientApplication Classe

L'app ha un client_id dopo averlo registrato in Interfaccia di amministrazione di Microsoft Entra.

Per PublicClientApplication, usare Nessuno qui.

Per ConfidentialClientApplication, supporta molti formati di input diversi per scenari diversi.

Supporto per l'uso di un segreto client. È sufficiente inserire un feed in una stringa, ad esempio "your client secret".

Supporto dell'uso di un certificato in formato X.509 (con estensione pem)Deprecated perché usa l'identificazione personale SHA-1,

a meno che non si stia ancora usando ADFS che supporta solo l'identificazione personale SHA-1. Usare l'opzione pfx documentata più avanti in questa pagina. Feed in un dict in questo formato:

   {
       "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 richiede un "private_key" in formato PEM. Se il certificato è in formato PKCS12 (pfx), è possibile convertirlo in formato X.509 (pem), da openssl pkcs12 -in file.pfx -out file.pem -nodes. L'identificazione personale è disponibile nella registrazione dell'app in portale di Azure. In alternativa, è possibile calcolare l'identificazione personale. public_certificate (facoltativo) è un certificato di chiave pubblica che verrà inviato tramite l'intestazione JWT 'x5c'. Ciò è utile quando si usa l'autenticazione con nome soggetto/autorità di certificazione , che è un approccio per semplificare la rotazione dei certificati. In base alle specifiche, "il certificato contenente la chiave pubblica corrispondente alla chiave usata per firmare digitalmente il JWS DEVE essere il primo certificato. Questo PUÒ essere seguito da certificati aggiuntivi, con ogni certificato successivo usato per certificare quello precedente". Tuttavia, l'autorità emittente del certificato può usare un ordine diverso. Pertanto, se il tentativo termina con un errore AADSTS700027 - "Il valore della firma specificato non corrisponde al valore della firma previsto", è possibile provare a usare solo il certificato foglia (in formato PEM/str).

Supporto dell'asserzione non elaborata ottenuta da altroveaggiunta nella versione 1.13.0:

Può anche essere un'asserzione completamente prefirmata che hai assemblato manualmente. È sufficiente passare un contenitore contenente solo la chiave "client_assertion", come illustrato di seguito:

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

Supporto della lettura dei certificati client dai file PFXQuesto utilizzo userà automaticamente l'identificazione personale SHA-256 del certificato. Aggiunta nella versione 1.29.0:

Feed in un dizionario contenente il percorso di un file PFX:

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

Il comando seguente genererà un file con estensione pfx dal file .key e pem:

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

L'autenticazione con nome soggetto/autorità di certificazione è un approccio per semplificare la rotazione dei certificati. Se il file con estensione pfx contiene sia la chiave privata che il certificato pubblico, è possibile acconsentire esplicitamente all'autenticazione nome soggetto/autorità emittente impostando "public_certificate" su True.

Aggiunta nella versione 0.5.0: si tratta di un dizionario di attestazioni aggiuntive firmate da questa ConfidentialClientApplication chiave privata. Ad esempio, è possibile usare {"client_ip": "x.x.x.x"}. È anche possibile eseguire l'override di una delle attestazioni predefinite seguenti:

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

URL che identifica un'autorità di token. Deve essere del formato https://login.microsoftonline.com/your_tenant Per impostazione predefinita, verrà usato https://login.microsoftonline.com/common

Modificata nella versione 1.17: è anche possibile usare una costante predefinita e un generatore simile al seguente:

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

(facoltativo) Attiva o disattiva la convalida dell'autorità. Questo parametro è true per impostazione predefinita.

Imposta la cache dei token usata da questa istanza di ClientApplication. Per impostazione predefinita, verrà creata e usata una cache in memoria.

(facoltativo) L'implementazione della classe astratta HttpClient <msal.oauth2cli.http.http_client> Defaults a un'istanza di sessione delle richieste. Poiché MSAL 1.11.0, la sessione predefinita sarà configurata per tentare un nuovo tentativo in caso di errore di connessione. Se si fornisce il proprio http_client, sarà il dovere dell'http_client decidere se eseguire un nuovo tentativo.

(facoltativo) Verrà passato al parametro verify nella libreria delle richieste sottostanti Questo non si applica se si è scelto di passare il proprio client Http

(facoltativo) Verrà passato al parametro proxy nella libreria delle richieste sottostanti Questo non si applica se si è scelto di passare il client Http personalizzato

(facoltativo) Verrà passato al parametro di timeout nella libreria delle richieste sottostante Questo non si applica se si è scelto di passare il proprio client Http

(facoltativo) È possibile specificare il nome dell'applicazione per Microsoft scopi di telemetria. Il valore predefinito è Nessuno, significa che non verrà passato a Microsoft.

(facoltativo) È possibile fornire la versione dell'applicazione per scopi di telemetria Microsoft. Il valore predefinito è Nessuno, significa che non verrà passato a Microsoft.

(facoltativo) Consente la configurazione di una o più funzionalità client, ad esempio ["CP1"].

La funzionalità client è destinata a informare il Microsoft Identity Platform (STS) per ciò che il client è in grado di supportare, in modo che il servizio token di sicurezza possa decidere di attivare determinate funzionalità. Ad esempio, se il client è in grado di gestire la richiesta di attestazioni, il servizio token di sicurezza potrebbe emettere token di accesso CAE (Continuous Access Evaluation) alle risorse, sapendo che quando la risorsa genera una richiesta di attestazioni il client sarà in grado di gestire tali sfide.

Dettagli di implementazione: la funzionalità client viene implementata usando il parametro "claims" in transito, per il momento. MSAL li combina in un parametro di attestazione che verrà fornito in un secondo momento tramite una della richiesta acquire-token.

(facoltativo) Indica a MSAL di usare il servizio token regionale Entra. Questa funzionalità legacy è disponibile solo per le applicazioni proprietarie. È supportato solo acquire_token_for_client().

Supporta 4 valori:

1. azure_region=None - Questo valore predefinito indica che non è configurata alcuna area. MSAL userà l'area definita in env var MSAL_FORCE_REGION.

2. azure_region="some_region" : indica che viene usata l'area specificata.

3. azure_region=True - ovvero MSAL tenterà di rilevare automaticamente l'area. Questo non è consigliato.

4. azure_region=False - ovvero MSAL non userà alcuna area.

Novità nella versione 1.12.0.

(facoltativo) Storicamente MSAL hardcodes offline_access ambito , che consentirebbe all'app di avere accesso prolungato ai dati dell'utente. Se non è necessario o indesiderato per l'app, è ora possibile usare questo parametro per fornire un elenco di esclusioni di ambiti, ad esempio exclude_scopes = ["offline_access"].

MSAL ha da molto tempo memorizzato nella cache i token in token_cache. Di recente, MSAL ha anche introdotto un concetto di http_cache, memorizzando automaticamente nella cache una quantità limitata di risposte HTTP non token, in modo che di lunga durataPublicClientApplication e ConfidentialClientApplication sarebbe più efficiente e reattivo in alcune situazioni.

Questo http_cache parametro accetta qualsiasi oggetto dict-like. Se non specificato, MSAL userà un dict in memoria.

Se l'app è un'app della riga di comando, è consigliabile rendere persistente il http_cache in diverse esecuzioni dell'interfaccia della riga di comando. Il formato del file persistente può cambiare a causa, ma non limitato al protocollo instabile, in modo che l'implementazione tolleri errori di caricamento imprevisti. La ricetta seguente illustra un modo per farlo:

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

I contenuti all'interno http_cache sono economici da ottenere. Non è necessario condividerli tra app diverse.

Il contenuto all'interno non conterrà token né informazioni personali.Content inside http_cache will contain no tokens nor Personally Identifiable Information (PII). La crittografia non è necessaria.

Novità nella versione 1.16.0.

In passato, MSAL si connetteva a un endpoint centrale in https://login.microsoftonline.com per acquisire alcuni metadati, soprattutto quando si usa un'autorità non familiare. Questo comportamento è noto come Individuazione istanza.

Per impostazione predefinita, questo parametro è Nessuno, che abilita l'individuazione dell'istanza.

Se si conoscono alcune autorità che consentono a MSAL di operare con as-is, senza coinvolgere l'individuazione di istanze, il modello consigliato è:

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

Se non si conoscono in anticipo alcune autorità, ma si vuole comunque che MSAL accetti qualsiasi autorità che si fornirà, è possibile usare un per False disabilitare in modo incondizionato l'individuazione dell'istanza.

Novità nella versione 1.19.0.

Deprecated. Per favore, usa enable_broker_on_windows invece.

Se abilitata, i log possono includere informazioni personali (informazioni personali). Ciò può essere utile per la risoluzione dei problemi relativi ai comportamenti del broker. Il comportamento predefinito è False.

Novità nella versione 1.24.0.

Aggiunta nella versione 1.28.0: è un URL che identifica un'autorità OIDC (OpenID Connect) del formato https://contoso.com/tenant. MSAL aggiungerà ".well-known/openid-configuration" all'autorità e recupererà i metadati OIDC da questa posizione per individuare gli endpoint.

Nota: Broker non verrà usato per l'autorità OIDC.