PublicClientApplication Classe

Igual que <xref:ClientApplication.__init__>, exceto que o client_credential parâmetro permanecerá None.

Note

O que é um corretor e por que o usar?

Um corretor é um componente instalado no seu dispositivo.

O Broker dá implicitamente ao teu dispositivo uma identidade. Ao utilizar um corretor,

O seu dispositivo torna-se um fator capaz de satisfazer a autenticação multifatoral (MFA).

Este fator tornar-se-ia obrigatório

se o administrador do inquilino permitir uma política correspondente de Acesso Condicional (CA).

A presença do corretor permite a plataforma de identidades da Microsoft

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

E isso é mais seguro.

Um benefício adicional do corretor é,

funciona como um processo de longa duração com o sistema operativo do seu dispositivo,

e mantém o seu próprio cache,

para que as suas aplicações ativadas pelo corretor (até uma linha de código)

podia automaticamente fazer SSO a partir de uma sessão já estabelecida e iniciada.

Como optar por usar o corretor?

Pode definir qualquer combinação dos seguintes parâmetros de opt-in para verdadeiro:

Bandeira de opt-in

Se a aplicação funcionar

A aplicação registou isto como um URI de redirecionamento da plataforma de ambiente de trabalho 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 Intune instalado

https://login.microsoftonline.com/common/oauth2/nativeclient (TEM de ser ativado)

Instalar dependência do broker,

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

Teste com acquire_token_interactive() e acquire_token_silent().

Os comportamentos de replio do suporte a brokers MSAL Python

O MSAL pode ou falhar erros ou recuar silenciosamente para fluxos que não são corretores.

A MSAL vai ignorar a enable_broker_... e corretor de desvio

nesses fluxos de autenticação que se sabe que NÃO são suportados pelo corretor.

Isto inclui ADFS, B2C, etc.

Para outros cenários de "corretor que poderia usar", veja abaixo.

O MSAL falha quando o programador da aplicação optou por usar o broker

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

Mensagem de erro orienta o programador de aplicações a declarar a dependência correta

MSAL [corretor].

Aqui erramos porque o erro é acionável para os programadores de aplicações.

O MSAL "desativa" silenciosamente o corretor e recua para não-corretor,

quando optava, a dependência instalava-se mas não se inicializava.

Prevemos que isto aconteça num dispositivo cujo sistema operativo é demasiado antigo

Ou o componente subjacente do corretor está de alguma forma indisponível.

Não há muito que um programador de aplicações ou o utilizador final possa fazer aqui.

Eventualmente, a política de acesso condicional deverá

Forçar o utilizador a mudar para outro dispositivo.

Erro MSAL quando o corretor é optado, instalado, inicializado,

mas os pedidos subsequentes de tokens 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

Name Descrição
enable_broker_on_windows
Obrigatório
<xref:boolean>

Esta configuração só é eficaz se a sua aplicação estiver a correr no Windows 10+. Este parâmetro é automaticamente Nenhum, o que significa que a MSAL não utilizará um corretor.

Novo em MSAL Python 1.25.0.
enable_broker_on_mac
Obrigatório
<xref:boolean>

Esta definição só é eficaz se a sua aplicação estiver a correr no Mac. Este parâmetro é automaticamente Nenhum, o que significa que a MSAL não utilizará um corretor.

Novidade em MSAL Python 1.31.0.
enable_broker_on_linux
Obrigatório
<xref:boolean>

Esta configuração só é eficaz se a sua aplicação estiver a correr em Linux, incluindo WSL. Este parâmetro é automaticamente Nenhum, o que significa que a MSAL não utilizará um corretor.

Novo em MSAL Python 1.33.0.
enable_broker_on_wsl
Obrigatório
<xref:boolean>

Esta definição só é eficaz se a sua aplicação estiver a correr em WSL. Este parâmetro é automaticamente Nenhum, o que significa que a MSAL não utilizará um corretor.

Novo em MSAL Python 1.33.0.
client_id
Obrigatório
client_credential
Valor predefinido: None

Parâmetros Só de Palavra-Chave

Name Descrição
enable_broker_on_windows
Valor predefinido: None
enable_broker_on_mac
Valor predefinido: None
enable_broker_on_linux
Valor predefinido: None
enable_broker_on_wsl
Valor predefinido: None

Métodos

acquire_token_by_device_flow

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

Adquira tokens de forma interativa, ou seja, através de um navegador local.

Pré-requisito: No portal do Azure, configure o URI de Redirecionamento da sua "Aplicação Mobile e Desktop" como http://localhost. Se optar por usar o broker durante a PublicClientApplication criação, a sua aplicação também precisa deste 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

Obter 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

Name Descrição
flow
Obrigatório
dict

Um ditto anteriormente gerado por initiate_device_flow. Por defeito, o efeito de sondagem deste método bloqueia a thread atual. Pode abortar o ciclo de sondagem a qualquer momento, alterando o valor da chave "expires_at" do fluxo para 0.
claims_challenge

O parâmetro claims_challenge solicita reivindicações específicas solicitadas pelo fornecedor de recursos sob a forma de uma diretiva claims_challenge no cabeçalho www-authenticate para serem devolvidas do UserInfo Endpoint e/ou no ID Token e/ou Access Token. É uma cadeia de caracteres de um objeto JSON que contém listas de reivindicações solicitadas a estas localizações.

Valor predefinido: None

Devoluções

Tipo Descrição

Um ditado que representa a resposta json da Microsoft Entra:

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

  • uma resposta de erro continha "erro" e normalmente "error_description".

acquire_token_interactive

Adquira tokens de forma interativa, ou seja, através de um navegador local.

Pré-requisito: No portal do Azure, configure o URI de Redirecionamento da sua "Aplicação Mobile e Desktop" como http://localhost. Se optar por usar o broker durante a PublicClientApplication criação, a sua aplicação também precisa deste 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

Name Descrição
scopes
Obrigatório
list

É uma lista de cordas sensíveis a maiúsculas e maiúsculas.
prompt
str

Por defeito, nenhum valor de prompt será enviado, nem sequer uma string "none". Terá de especificar um valor explicitamente. Os seus valores válidos são as constantes definidas em <xref:msal.Prompt>.

Valor predefinido: None
login_hint
str

Optional. Identificador do utilizador. Geralmente, um nome principal de utilizador (UPN).

Valor predefinido: None
domain_hint

Pode ser um dos "consumidores" ou "organizações" ou do seu domínio de inquilino "contoso.com". Se incluído, saltará o processo de descoberta por email que o utilizador realiza na página de iniciação de sessão, levando a uma experiência de utilizador um pouco mais simplificada. Mais informações sobre valores possíveis disponíveis no documento Auth Code Flow e no documento domain_hint.

Valor predefinido: None
claims_challenge

O parâmetro claims_challenge solicita reivindicações específicas solicitadas pelo fornecedor de recursos sob a forma de uma diretiva claims_challenge no cabeçalho www-authenticate para serem devolvidas do UserInfo Endpoint e/ou no ID Token e/ou Access Token. É uma cadeia de caracteres de um objeto JSON que contém listas de reivindicações solicitadas a estas localizações.

Valor predefinido: None
timeout
int

Este método irá bloquear o fio atual. Este parâmetro especifica o valor de timeout em segundos. Valor None padrão significa esperar indefinidamente.

Valor predefinido: None
port
int

A porta a ser usada para ouvir uma resposta de autorização recebida. Por defeito, usaremos uma porta atribuída ao sistema. (O resto da redirect_uri está codificado como http://localhost.)

Valor predefinido: None
extra_scopes_to_consent
list

"Limites extra para consentimento" é um conceito disponível apenas no Microsoft Entra. Refere-se a outros recursos que possas querer pedir para consentir, na mesma interação, mas para os quais não receberás um token nesta operação em particular.

Valor predefinido: None
max_age
int

OPCIONAL. Idade máxima de autenticação. Especifica o tempo decorrido permitido em segundos desde a última vez que o End-User foi autenticado ativamente. Se o tempo decorrido for superior a este valor, a plataforma de identidades da Microsoft irá re-autenticar ativamente o Utilizador Final.

O MSAL Python também valida automaticamente a auth_time no token ID.

Novo na versão 1.15.

Valor predefinido: None
parent_window_handle
int

OPCIONAL.

  • Se a sua aplicação não optar por usar o corretor, não precisa de fornecer um parent_window_handle aqui.

  • Se a sua aplicação optar por usar o corretor, parent_window_handle é obrigatório.

    • Se a sua aplicação for uma aplicação com interface gráfica a correr no sistema Windows ou Mac, é obrigado também a fornecer o seu handler de janela, para que a janela de início de sessão apareça em cima da sua janela.

    • Se a sua aplicação for uma aplicação de consola a correr no sistema Windows ou Mac, pode usar um marcador PublicClientApplication.CONSOLE_WINDOW_HANDLEde posição .

A maioria dos scripts em Python são aplicações de consola.

Novo na versão 1.20.0.

Valor predefinido: None
on_before_launching_ui
<xref:function>

Um callback com a forma de lambda ui="xyz", **kwargs: print("A {} will be launched".format(ui)), onde ui será ou "browser" ou "broker". Pode usá-lo para informar o utilizador final para esperar uma janela pop-up.

Novo na versão 1.20.0.

Valor predefinido: None
auth_scheme
object

Pode fornecer um msal.auth_scheme.PopAuthScheme objeto para que a MSAL receba um token de Prova de Posse (POP) para si.

Novo na versão 1.26.0.

Valor predefinido: None

Devoluções

Tipo Descrição

  • Um dict que não contém uma tecla de "erro" e normalmente contém uma tecla de "access_token".

  • Um dict contendo 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

Name Descrição
scopes
list[str]

Escopos solicitados para aceder a uma API protegida (um recurso).

Valor predefinido: None

Parâmetros Só de Palavra-Chave

Name Descrição
claims_challenge
Valor predefinido: None

Devoluções

Tipo Descrição

Um dict que representa um objeto Device Flow recém-criado.

  • Uma resposta bem-sucedida incluiria a tecla "user_code", entre outras

  • uma resposta de erro conteria 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'