ClientApplication Classe

Seu aplicativo tem um client_id depois de registrá-lo no centro de administração do Microsoft Entra.

Para PublicClientApplication, você usa Nenhum aqui.

Para ConfidentialClientApplication, ele dá suporte a muitos formatos de entrada diferentes para cenários diferentes.

Suporte ao uso de um segredo do cliente. Basta alimentar em uma cadeia de caracteres, como "your client secret".

Suporte ao uso de um certificado no formato X.509 (.pem)Deprecated porque ele usa a impressão digital SHA-1,

a menos que você ainda esteja usando o ADFS que dá suporte apenas à impressão digital SHA-1. Use a opção .pfx documentada posteriormente nesta página. Feed em um ditado neste formulário:

   {
       "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.
   }

O Python MSAL requer um "private_key" no formato PEM. Se o certificado estiver no formato PKCS12 (.pfx), você poderá convertê-lo no formato X.509 (.pem) por openssl pkcs12 -in file.pfx -out file.pem -nodes. A impressão digital está disponível no registro do aplicativo no portal do Azure. Como alternativa, você pode calcular a impressão digital. public_certificate (opcional) é um certificado de chave pública que será enviado por meio do cabeçalho JWT 'x5c'. Isso é útil quando você usa o Nome da Entidade/Autenticação do Emissor , que é uma abordagem para permitir uma rotação de certificado mais fácil. Por especificações, "o certificado que contém a chave pública correspondente à chave usada para assinar digitalmente o JWS DEVE ser o primeiro certificado. Isso pode ser seguido por certificados adicionais, com cada certificado subsequente sendo o usado para certificar o anterior." No entanto, o emissor do certificado pode usar uma ordem diferente. Portanto, se sua tentativa acabar com um erro AADSTS700027 - "O valor de assinatura fornecido não correspondeu ao valor de assinatura esperado", você poderá tentar usar apenas o certificado folha (no formato PEM/str).

Suporte à declaração bruta obtida de outro lugaradicionado na versão 1.13.0:

Também pode ser uma afirmação completamente pré-assinada que você mesmo montou. Basta passar um contêiner contendo apenas a chave "client_assertion", desta forma:

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

Suporte à leitura de certificados de cliente de arquivos PFX Esse uso usará automaticamente a impressão digital SHA-256 do certificado. Adicionado na versão 1.29.0:

Feed em um dicionário que contém o caminho para um arquivo 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)",
   }

O comando a seguir gerará um arquivo .pfx de seu arquivo .key e .pem:

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

Nome da Entidade/Autenticação do Emissor é uma abordagem para permitir uma rotação de certificado mais fácil. Se o arquivo .pfx contiver a chave privada e o certificado público, você poderá optar pelo Nome da Entidade/Autenticação do Emissor definindo "public_certificate" como True.

Adicionado na versão 0.5.0: é um dicionário de declarações extras que seriam assinadas por essa ConfidentialClientApplication chave privada. Por exemplo, você pode usar {"client_ip": "x.x.x.x"}. Você também pode substituir qualquer uma das seguintes declarações padrão:

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

Uma URL que identifica uma autoridade de token. Deve ser do formato https://login.microsoftonline.com/your_tenant Por padrão, usaremos https://login.microsoftonline.com/common

Alterado na versão 1.17: você também pode usar a constante predefinida e um construtor 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) Ativa ou desativa a validação de autoridade. Esse parâmetro é padrão como true.

Define o cache de token usado por esta instância clientApplication. Por padrão, um cache na memória será criado e usado.

(opcional) Sua implementação da classe abstrata HttpClient <msal.oauth2cli.http.http_client> Padrões para uma instância de sessão de solicitações. Como MSAL 1.11.0, a sessão padrão seria configurada para tentar uma nova tentativa de erro de conexão. Se você estiver fornecendo seu próprio http_client, será dever do seu http_client decidir se deseja executar novamente.

(opcional) Ele será passado para o parâmetro de verificação na biblioteca de solicitações subjacentes Isso não se aplica se você optou por passar seu próprio cliente Http

(opcional) Ele será passado para o parâmetro proxies na biblioteca de solicitações subjacentes Isso não se aplica se você tiver escolhido passar seu próprio cliente Http

(opcional) Ele será passado para o parâmetro de tempo limite na biblioteca de solicitações subjacentes Isso não se aplica se você optou por passar seu próprio cliente Http

(opcional) Você pode fornecer o nome do aplicativo para fins de telemetria Microsoft. O valor padrão é None, significa que ele não será passado para Microsoft.

(opcional) Você pode fornecer a versão do aplicativo para fins de telemetria Microsoft. O valor padrão é None, significa que ele não será passado para Microsoft.

(opcional) Permite a configuração de um ou mais recursos de cliente, por exemplo, ["CP1"].

A funcionalidade do cliente destina-se a informar ao plataforma de identidade da Microsoft (STS) para o qual esse cliente é capaz, para que o STS possa decidir ativar determinados recursos. Por exemplo, se o cliente for capaz de lidar com o desafio de declarações, o STS poderá emitir tokens de acesso da CAE (Avaliação Contínua de Acesso) aos recursos, sabendo que quando o recurso emitir um desafio de declarações , o cliente poderá lidar com esses desafios.

Detalhes da implementação: a funcionalidade do cliente é implementada usando o parâmetro "declarações" no fio, por enquanto. A MSAL irá combiná-las no parâmetro de declarações que você fornecerá posteriormente por meio de uma das solicitações de token de aquisição.

(opcional) Instrui a MSAL a usar o serviço de token regional do Entra. Esse recurso herdado só está disponível para aplicativos de primeira parte. Há suporte apenas para acquire_token_for_client().

Dá suporte a 4 valores:

1. azure_region=None - Esse valor padrão significa que nenhuma região está configurada. A MSAL usará a região definida em env var MSAL_FORCE_REGION.

2. azure_region="some_region" - o que significa que a região especificada é usada.

3. azure_region=True - o que significa que a MSAL tentará detectar automaticamente a região. Isso não é recomendado.

4. azure_region=False - o que significa que a MSAL não usará nenhuma região.

Novo na versão 1.12.0.

(opcional) Historicamente, os códigos rígidos msal offline_access escopo, o que permitiria que seu aplicativo tivesse acesso prolongado aos dados do usuário. Se isso for desnecessário ou indesejável para seu aplicativo, agora você poderá usar esse parâmetro para fornecer uma lista de exclusão de escopos, como exclude_scopes = ["offline_access"].

A MSAL está armazenando tokens em cache há muito tempo no token_cache. Recentemente, a MSAL também introduziu um conceito de http_cache, armazenando automaticamente alguma quantidade finita de respostas http não token, de modo que a vidaPublicClientApplication útil e ConfidentialClientApplication seria mais performante e responsiva em algumas situações.

Esse http_cache parâmetro aceita qualquer objeto semelhante a ditado. Se não for fornecido, a MSAL usará um ditado na memória.

Se seu aplicativo for um aplicativo de linha de comando (CLI), você desejará manter seu http_cache em diferentes execuções da CLI. O formato do arquivo persistente pode ser alterado devido, mas não se limitando ao protocolo instável, portanto, sua implementação deve tolerar erros de carregamento inesperados. A receita a seguir mostra uma maneira de fazer isso:

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

O conteúdo dentro http_cache é barato de obter. Não é necessário compartilhá-los entre aplicativos diferentes.

O conteúdo dentro http_cache não conterá tokens nem PII (Informações de Identificação Pessoal). A criptografia é desnecessária.

Novo na versão 1.16.0.

Historicamente, a MSAL se conectaria a um ponto de extremidade central localizado https://login.microsoftonline.com para adquirir alguns metadados, especialmente ao usar uma autoridade desconhecida. Esse comportamento é conhecido como Descoberta de Instância.

Esse parâmetro usa como padrão None, que habilita a Descoberta de Instância.

Se você souber algumas autoridades que permitem que a MSAL opere com as-is, sem envolver nenhuma Descoberta de Instância, o padrão recomendado é:

   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 você não conhece algumas autoridades de antemão, ainda quer que a MSAL aceite qualquer autoridade que você fornecerá, você pode usar uma False para desabilitar incondicionalmente a Descoberta de Instâncias.

Novo na versão 1.19.0.

Preterido. Use enable_broker_on_windows em seu lugar.

Quando habilitados, os logs podem incluir PII (Informações de Identificação Pessoal). Isso pode ser útil na solução de problemas de comportamentos do agente. O comportamento padrão é False.

Novo na versão 1.24.0.

Adicionado na versão 1.28.0: é uma URL que identifica uma autoridade do OpenID Connect (OIDC) do formato https://contoso.com/tenant. A MSAL anexará ".well-known/openid-configuration" à autoridade e recuperará os metadados do OIDC a partir daí, para descobrir os pontos de extremidade.

Observação: O agente NÃO será usado para a autoridade OIDC.