PublicClientApplication Classe

O mesmo que <xref:ClientApplication.__init__>, exceto que o client_credential parâmetro deve permanecer None.

Note

O que é um agente e por que usá-lo?

Um agente é um componente instalado em seu dispositivo.

O agente fornece implicitamente uma identidade ao seu dispositivo. Usando um agente,

seu dispositivo se torna um fator que pode satisfazer a MFA (autenticação multifator).

Esse fator se tornaria obrigatório

se o administrador de um locatário habilitar uma política de AC (Acesso Condicional) correspondente.

A presença do agente permite plataforma de identidade da Microsoft

para ter maior confiança de que os tokens estão sendo emitidos para seu dispositivo,

e isso é mais seguro.

Um benefício adicional do agente é,

ele é executado como um processo de longa duração com o sistema operacional do dispositivo,

e mantém seu próprio cache,

para que seus aplicativos habilitados para agente (até mesmo uma CLI)

poderia ser SSO automaticamente de uma sessão de entrada estabelecida anteriormente.

Como optar por usar o agente?

Você pode definir qualquer combinação dos seguintes parâmetros de aceitação como true:

Sinalizador de aceitação

Se o aplicativo for executado em

O aplicativo registrou isso como um URI de redirecionamento da plataforma desktop no portal do Azure

enable_broker_on_windows

Windows 10+

ms-appx-web://Microsoft. AAD. BrokerPlugin/your_client_id

enable_broker_on_wsl

WSL

ms-appx-web://Microsoft. AAD. BrokerPlugin/your_client_id

enable_broker_on_mac

Mac com Portal da Empresa instalado

msauth.com.msauth.unsignedapp://auth

enable_broker_on_linux

Linux com o Intune instalado

https://login.microsoftonline.com/common/oauth2/nativeclient (DEVE ser habilitado)

Instalar dependência do agente,

por exemplo, pip install msal[broker]>=1.33,2<.

Teste com acquire_token_interactive() e acquire_token_silent().

Os comportamentos de fallback do suporte do agente do Python da MSAL

A MSAL fará um erro ou fará fallback silenciosamente em fluxos que não são do agente.

A MSAL ignorará a enable_broker_... e o agente de bypass

nesses fluxos de autenticação que são conhecidos por não serem compatíveis com o agente.

Isso inclui ADFS, B2C, etc..

Para outros cenários de "pode-usar agente", consulte abaixo.

A MSAL errou quando o desenvolvedor de aplicativos optou por usar o agente

mas um pacote "mid-tier" de dependência direta não está instalado.

Mensagem de erro orienta desenvolvedor de aplicativo a declarar a dependência correta

msal[broker].

Erro aqui porque o erro é acionável para os desenvolvedores de aplicativos.

A MSAL silenciosamente "desativa" o agente e o fallback para não agente,

quando opted-in, a dependência instalada ainda não foi inicializada.

Prevíamos que isso aconteceria em um dispositivo cujo sistema operacional é muito antigo

ou o componente do agente subjacente está de alguma forma indisponível.

Não há muito que um desenvolvedor de aplicativos ou o usuário final possa fazer aqui.

Eventualmente, a política de acesso condicional deverá

force o usuário a alternar para um dispositivo diferente.

A MSAL ocorre quando o agente é optado, instalado, inicializado,

mas as solicitações de token subsequentes falharam.

Construtor

PublicClientApplication(client_id, client_credential=None, *, enable_broker_on_windows=None, enable_broker_on_mac=None, enable_broker_on_linux=None, enable_broker_on_wsl=None, **kwargs)

Parâmetros

Nome Description
enable_broker_on_windows
Obrigatório
<xref:boolean>

Essa configuração só será eficaz se o aplicativo estiver em execução no Windows 10+. Esse parâmetro usa como padrão None, o que significa que a MSAL não utilizará um agente.

Novidades na MSAL Python 1.25.0.
enable_broker_on_mac
Obrigatório
<xref:boolean>

Essa configuração só será efetiva se o aplicativo estiver em execução no Mac. Esse parâmetro usa como padrão None, o que significa que a MSAL não utilizará um agente.

Novidades na MSAL Python 1.31.0.
enable_broker_on_linux
Obrigatório
<xref:boolean>

Essa configuração só será eficaz se o aplicativo estiver em execução no Linux, incluindo o WSL. Esse parâmetro usa como padrão None, o que significa que a MSAL não utilizará um agente.

Novidades na MSAL Python 1.33.0.
enable_broker_on_wsl
Obrigatório
<xref:boolean>

Essa configuração só será eficaz se o aplicativo estiver em execução no WSL. Esse parâmetro usa como padrão None, o que significa que a MSAL não utilizará um agente.

Novidades na MSAL Python 1.33.0.
client_id
Obrigatório
client_credential
Valor padrão: None

Parâmetros somente de palavra-chave

Nome Description
enable_broker_on_windows
Valor padrão: None
enable_broker_on_mac
Valor padrão: None
enable_broker_on_linux
Valor padrão: None
enable_broker_on_wsl
Valor padrão: None

Métodos

acquire_token_by_device_flow

Obtenha o token por um objeto de fluxo de dispositivo, com efeito de sondagem personalizável.
acquire_token_interactive

Adquira o token interativamente, ou seja, por meio de um navegador local.

Pré-requisito: em portal do Azure, configure o URI de Redirecionamento do seu "aplicativo móvel e de área de trabalho" como http://localhost. Se você optar por usar o agente durante PublicClientApplication a criação, seu aplicativo também precisará desse URI de Redirecionamento: ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID
initiate_device_flow

Inicie uma instância de Fluxo de Dispositivo, que será usada em acquire_token_by_device_flow.

acquire_token_by_device_flow

Obtenha o token por um objeto de fluxo de dispositivo, com efeito de sondagem personalizável.

acquire_token_by_device_flow(flow, claims_challenge=None, **kwargs)

Parâmetros

Nome Description
flow
Obrigatório
dict

Um ditado gerado anteriormente por initiate_device_flow. Por padrão, o efeito de sondagem desse método bloqueará o thread atual. Você pode anular o loop de sondagem a qualquer momento, alterando o valor da chave "expires_at" do fluxo para 0.
claims_challenge

O parâmetro claims_challenge solicita declarações específicas solicitadas pelo provedor de recursos na forma de uma diretiva claims_challenge no cabeçalho www-authenticate a ser retornado do Ponto de Extremidade UserInfo e/ou no Token de ID e/ou Token de Acesso. É uma cadeia de caracteres de um objeto JSON que contém listas de declarações que estão sendo solicitadas desses locais.

Valor padrão: None

Retornos

Tipo Description

Um ditado que representa a resposta json de Microsoft Entra:

  • Uma resposta bem-sucedida conteria a chave "access_token",

  • uma resposta de erro conteria "erro" e geralmente "error_description".

acquire_token_interactive

Adquira o token interativamente, ou seja, por meio de um navegador local.

Pré-requisito: em portal do Azure, configure o URI de Redirecionamento do seu "aplicativo móvel e de área de trabalho" como http://localhost. Se você optar por usar o agente durante PublicClientApplication a criação, seu aplicativo também precisará desse URI de Redirecionamento: ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID

acquire_token_interactive(scopes, prompt=None, login_hint=None, domain_hint=None, claims_challenge=None, timeout=None, port=None, extra_scopes_to_consent=None, max_age=None, parent_window_handle=None, on_before_launching_ui=None, auth_scheme=None, **kwargs)

Parâmetros

Nome Description
scopes
Obrigatório
list

É uma lista de cadeias de caracteres que diferenciam maiúsculas de minúsculas.
prompt
str

Por padrão, nenhum valor de prompt será enviado, nem mesmo cadeia de caracteres "none". Você precisará especificar um valor explicitamente. Seus valores válidos são as constantes definidas em <xref:msal.Prompt>.

Valor padrão: None
login_hint
str

Optional. Identificador do utilizador. Geralmente, um nome upn (nome de entidade de usuário).

Valor padrão: None
domain_hint

Pode ser um dos "consumidores" ou "organizações" ou seu domínio de locatário "contoso.com". Se incluído, ele ignorará o processo de descoberta baseado em email pelo qual o usuário passa na página de entrada, levando a uma experiência de usuário um pouco mais simplificada. Mais informações sobre os valores possíveis disponíveis no documento do Fluxo de Código de Autenticação e domain_hint documento.

Valor padrão: None
claims_challenge

O parâmetro claims_challenge solicita declarações específicas solicitadas pelo provedor de recursos na forma de uma diretiva claims_challenge no cabeçalho www-authenticate a ser retornado do Ponto de Extremidade UserInfo e/ou no Token de ID e/ou Token de Acesso. É uma cadeia de caracteres de um objeto JSON que contém listas de declarações que estão sendo solicitadas desses locais.

Valor padrão: None
timeout
int

Esse método bloqueará o thread atual. Esse parâmetro especifica o valor do tempo limite em segundos. O valor None padrão significa aguardar indefinidamente.

Valor padrão: None
port
int

A porta a ser usada para ouvir uma resposta de autenticação de entrada. Por padrão, usaremos uma porta alocada pelo sistema. (O restante do redirect_uri é codificado como http://localhost.)

Valor padrão: None
extra_scopes_to_consent
list

"Escopos extras para consentir" é um conceito disponível apenas em Microsoft Entra. Ele se refere a outros recursos que talvez você queira solicitar consentimento, na mesma interação, mas para os quais você não receberá de volta um token para esta operação específica.

Valor padrão: None
max_age
int

OPCIONAL. Idade máxima de autenticação. Especifica o tempo decorrido permitido em segundos desde a última vez em que o End-User foi autenticado ativamente. Se o tempo decorrido for maior que esse valor, plataforma de identidade da Microsoft autenticará ativamente o Usuário Final novamente.

O Python MSAL também validará automaticamente o auth_time no token de ID.

Novo na versão 1.15.

Valor padrão: None
parent_window_handle
int

OPCIONAL.

  • Se seu aplicativo não optar por usar o agente, você não precisará fornecer um parent_window_handle aqui.

  • Se o aplicativo optar por usar o agente, parent_window_handle será necessário.

    • Se seu aplicativo for um aplicativo gui em execução no sistema Windows ou Mac, você também precisará fornecer seu identificador de janela para que a janela de entrada apareça na parte superior da janela.

    • Se o aplicativo for um aplicativo de console em execução no sistema Windows ou Mac, você poderá usar um espaço reservadoPublicClientApplication.CONSOLE_WINDOW_HANDLE.

A maioria dos scripts Python são aplicativos de console.

Novo na versão 1.20.0.

Valor padrão: None
on_before_launching_ui
<xref:function>

Um retorno de chamada com a forma de lambda ui="xyz", **kwargs: print("A {} will be launched".format(ui)), onde ui será "navegador" ou "agente". Você pode usá-lo para informar o usuário final para esperar uma janela pop-up.

Novo na versão 1.20.0.

Valor padrão: None
auth_scheme
object

Você pode fornecer um msal.auth_scheme.PopAuthScheme objeto para que a MSAL obtenha um token POP (Prova de Posse) para você.

Novo na versão 1.26.0.

Valor padrão: None

Retornos

Tipo Description

  • Um ditado que não contém nenhuma chave de "erro" e normalmente contém uma chave "access_token".

  • Um ditado que contém uma chave de "erro", quando a atualização do token falhou.

initiate_device_flow

Inicie uma instância de Fluxo de Dispositivo, que será usada em acquire_token_by_device_flow.

initiate_device_flow(scopes=None, *, claims_challenge=None, **kwargs)

Parâmetros

Nome Description
scopes
list[str]

Escopos solicitados para acessar uma API protegida (um recurso).

Valor padrão: None

Parâmetros somente de palavra-chave

Nome Description
claims_challenge
Valor padrão: None

Retornos

Tipo Description

Um ditado que representa um objeto de Fluxo de Dispositivo recém-criado.

  • Uma resposta bem-sucedida conteria a chave "user_code", entre outros

  • uma resposta de erro conteria alguns outros pares chave/valor legíveis.

Atributos

CONSOLE_WINDOW_HANDLE 

CONSOLE_WINDOW_HANDLE = <object object>

DEVICE_FLOW_CORRELATION_ID 

DEVICE_FLOW_CORRELATION_ID = '_correlation_id'