ClientApplication Clase

La aplicación tiene un client_id después de registrarla en Centro de administración Microsoft Entra.

Para PublicClientApplication, use None aquí.

Para ConfidentialClientApplication, admite muchos formatos de entrada diferentes para distintos escenarios.

Compatibilidad con el uso de un secreto de cliente. Simplemente se alimenta en una cadena, como "your client secret".

Compatibilidad con el uso de un certificado en formato X.509 (.pem) En desuso porque usa la huella digital SHA-1,

a menos que siga usando ADFS, que solo admite huella digital SHA-1. Use la opción .pfx documentada más adelante en esta página. Fuente en un dict en este 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 requiere un "private_key" en formato PEM. Si el certificado está en formato PKCS12 (.pfx), puede convertirlo a formato X.509 (.pem), por openssl pkcs12 -in file.pfx -out file.pem -nodes. La huella digital está disponible en el registro de la aplicación en Azure Portal. Como alternativa, puede calcular la huella digital. public_certificate (opcional) es un certificado de clave pública que se enviará a través del encabezado JWT "x5c". Esto resulta útil cuando se usa la autenticación del emisor o el nombre del firmante , que es un enfoque para permitir una rotación de certificados más sencilla. Según las especificaciones, "el certificado que contiene la clave pública correspondiente a la clave utilizada para firmar digitalmente el JWS DEBE ser el primer certificado. Esto puede ir seguido de certificados adicionales, y cada certificado posterior es el que se usa para certificar el anterior". Sin embargo, el emisor del certificado puede usar un orden diferente. Por lo tanto, si el intento termina con un error AADSTS700027: "El valor de firma proporcionado no coincide con el valor de firma esperado", puede intentar usar solo el certificado hoja (en formato PEM/str) en su lugar.

Compatibilidad con la aserción sin procesar obtenida de otra parteAgregada en la versión 1.13.0:

También puede ser una aserción completamente firmada previamente que ha ensamblado usted mismo. Simplemente pase un contenedor que contenga solo la clave "client_assertion", de la siguiente manera:

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

Admitir la lectura de certificados de cliente de archivos PFXEste uso usará automáticamente la huella digital SHA-256 del certificado. Agregado en la versión 1.29.0:

Fuente en un diccionario que contiene la ruta de acceso a un archivo 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)",
   }

El siguiente comando generará un archivo .pfx desde el archivo .key y .pem:

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

La autenticación del firmante o el emisor es un enfoque para permitir una rotación de certificados más sencilla. Si el archivo .pfx contiene la clave privada y el certificado público, puede optar por la autenticación del firmante o del emisor estableciendo "public_certificate" en True.

Agregado en la versión 0.5.0: es un diccionario de notificaciones adicionales firmadas por esta ConfidentialClientApplication clave privada. Por ejemplo, puede usar {"client_ip": "x.x.x.x"}. También puede invalidar cualquiera de las siguientes notificaciones predeterminadas:

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

Dirección URL que identifica una entidad de token. Debe tener el formato https://login.microsoftonline.com/your_tenant De forma predeterminada, usaremos https://login.microsoftonline.com/common

Cambiado en la versión 1.17: también puede usar una constante predefinida y un generador como este:

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

(opcional) Activa o desactiva la validación de autoridad. Este parámetro tiene como valor predeterminado true.

Establece la caché de tokens usada por esta instancia de ClientApplication. De forma predeterminada, se creará y usará una caché en memoria.

(opcional) La implementación de la clase abstracta HttpClient <msal.oauth2cli.http.http_client> valores predeterminados en una instancia de sesión de solicitudes. Dado que MSAL 1.11.0, la sesión predeterminada se configuraría para intentar un reintento en el error de conexión. Si proporciona su propio http_client, será su deber de http_client decidir si debe realizar el reintento.

(opcional) Se pasará al parámetro verify en la biblioteca de solicitudes subyacentes . Esto no se aplica si ha elegido pasar su propio cliente Http.

(opcional) Se pasará al parámetro proxies en la biblioteca de solicitudes subyacentes . Esto no se aplica si ha elegido pasar su propio cliente Http.

(opcional) Se pasará al parámetro timeout en la biblioteca de solicitudes subyacentes . Esto no se aplica si ha elegido pasar su propio cliente Http.

(opcional) Puede proporcionar el nombre de la aplicación para Microsoft fines de telemetría. El valor predeterminado es None, significa que no se pasará a Microsoft.

(opcional) Puede proporcionar la versión de la aplicación con fines de telemetría Microsoft. El valor predeterminado es None, significa que no se pasará a Microsoft.

(opcional) Permite la configuración de una o varias funcionalidades de cliente, por ejemplo, ["CP1"].

La funcionalidad de cliente está pensada para informar al Plataforma de identidad de Microsoft (STS) de lo que este cliente es capaz de, por lo que STS puede decidir activar determinadas características. Por ejemplo, si el cliente es capaz de controlar el desafío de notificaciones, STS puede emitir tokens de acceso continuo (CAE) a los recursos, sabiendo que cuando el recurso emite un desafío de notificaciones , el cliente podrá controlar esos desafíos.

Detalles de implementación: la funcionalidad del cliente se implementa mediante el parámetro "claims" en la conexión, por ahora. MSAL los combinará en el parámetro de notificaciones que proporcionará más adelante a través de una de las solicitudes de acquire-token.

(opcional) Indica a MSAL que use el servicio de token regional entra. Esta característica heredada solo está disponible para aplicaciones propias. Solo acquire_token_for_client() es compatible.

Admite 4 valores:

1. azure_region=None : este valor predeterminado significa que no hay ninguna región configurada. MSAL usará la región definida en env var MSAL_FORCE_REGION.

2. azure_region="some_region" : significa que se usa la región especificada.

3. azure_region=True : significa que MSAL intentará detectar automáticamente la región. Esto no se recomienda.

4. azure_region=False : significa que MSAL no usará ninguna región.

Novedad de la versión 1.12.0.

(opcional) Históricamente, MSAL codifica de forma offline_access ámbito, lo que permitiría que la aplicación tuviera acceso prolongado a los datos del usuario. Si es innecesario o no deseado para la aplicación, ahora puedes usar este parámetro para proporcionar una lista de exclusión de ámbitos, como exclude_scopes = ["offline_access"].

MSAL ha estado almacenando en caché tokens durante mucho tiempo en .token_cache Recientemente, MSAL también introdujo un concepto de http_cache, almacenando automáticamente en caché cierta cantidad finita de respuestas http que no son de token, de modo que la larga duraciónPublicClientApplication y ConfidentialClientApplication sería más eficaz y con capacidad de respuesta en algunas situaciones.

Este http_cache parámetro acepta cualquier objeto de tipo dict. Si no se proporciona, MSAL usará un dict en memoria.

Si la aplicación es una aplicación de línea de comandos (CLI), querrá conservar la http_cache en distintas ejecuciones de la CLI. El formato del archivo persistente puede cambiar debido, entre otros, al protocolo inestable, por lo que la implementación tolerará errores de carga inesperados. La siguiente receta muestra una manera de hacerlo:

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

El contenido dentro http_cache es barato para obtener. No es necesario compartirlos entre diferentes aplicaciones.

El contenido dentro http_cache no contendrá tokens ni información de identificación personal (PII). El cifrado no es necesario.

Novedades de la versión 1.16.0.

Históricamente, MSAL se conectaría a un punto de conexión central ubicado en https://login.microsoftonline.com para adquirir algunos metadatos, especialmente cuando se usa una entidad desconocida. Este comportamiento se conoce como Detección de instancias.

Este parámetro tiene como valor predeterminado None, que habilita la detección de instancias.

Si conoce algunas autoridades que permiten que MSAL funcione con as-is, sin implicar ninguna detección de instancias, el patrón recomendado es:

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

Si no conoce a algunas autoridades de antemano, todavía quiere que MSAL acepte cualquier autoridad que proporcione, puede usar para False deshabilitar incondicionalmente la detección de instancias.

Novedad de la versión 1.19.0.

Deprecated. Utilice enable_broker_on_windows en su lugar.

Cuando se habilita, los registros pueden incluir PII (información de identificación personal). Esto puede ser útil para solucionar problemas de comportamientos de agente. El comportamiento predeterminado es False.

Novedad de la versión 1.24.0.

Agregado en la versión 1.28.0: es una dirección URL que identifica una entidad de OpenID Connect (OIDC) del formato https://contoso.com/tenant. MSAL anexará ".well-known/openid-configuration" a la autoridad y recuperará los metadatos de OIDC desde allí para averiguar los puntos de conexión.

Nota: El agente NO se usará para la autoridad de OIDC.