Obter tokens

Há muitas maneiras de adquirir um token com Python MSAL. Alguns exigem interação do usuário, enquanto outros não. A abordagem usada para adquirir um token é diferente dependendo se o desenvolvedor está criando um cliente público (desktop ou móvel) ou um aplicativo cliente confidencial (aplicativo Web, API Web ou daemon como um serviço de Windows).

Pré-requisitos

Antes de adquirir tokens com Python MSAL, saiba mais sobre os tipos de aplicativo cliente.

Obter conta de usuário

Um aplicativo pode adquirir um token como ele mesmo ou em nome de um usuário. Para adquirir um token em nome de um usuário, o aplicativo precisa conhecer a conta do usuário. A MSAL Python fornece o get_accounts método para obter a conta do usuário. Este método está disponível nas classes PublicClientApplication e ConfidentialClientApplication. O método retorna uma lista de contas com as quais o usuário entrou anteriormente, ou seja, existe no cache.

accounts = app.get_accounts(username=user.get("preferred_username"))

A conta selecionada pelo usuário para fazer login pode ser usada posteriormente em acquire_token_silent() para localizar seus tokens.

Fluxos de concessão de token

Há vários fluxos de autenticação que podem ser usados para adquirir tokens com Python MSAL. Você pode encontrar mais informações sobre esses fluxos na documentação do plataforma de identidade da Microsoft.

Interativo vs silencioso

O Python MSAL dá suporte à aquisição de token interativa e silenciosa. A aquisição interativa de token requer interação do usuário, enquanto a aquisição de token silencioso não. Os clientes públicos geralmente exigem interação do usuário, enquanto os clientes confidenciais dependem de credenciais pré-provisionadas, como certificados e segredos.

Use o acquire_token_silent_with_error método para adquirir silenciosamente um token. Esse método localiza um token de acesso válido do cache ou um token de atualização válido do cache e o usa automaticamente para resgatar um novo token de acesso. Se nenhum dos dois for verdadeiro, você precisará usar um método interativo para adquirir o token.

Se o aplicativo não precisar considerar o erro exato de atualização de token durante a busca no cache de token, o método acquire_token_silent é recomendado.

Um exemplo de uso desse método é mostrado no snippet de código a seguir.

if accounts:
    # If so, you could then somehow display these accounts and let end user choose
    chosen = accounts[0]
    result = app.acquire_token_silent(scopes=["your_scope"], account=chosen)
    
    # At this point, you can save you can update your cache if you are using token caching
    # check result variable, if its None then you should interactively acquire a token
    if not result:
        # So no suitable token exists in cache. Let's get a new one from Microsoft Entra.
        result = app.acquire_token_by_one_of_the_actual_method(..., scopes=["User.Read"])
    
    if "access_token" in result:
        access_token = result["access_token"]
    else:
        print(result.get("error"))  
        print(result.get("error_description"))
        print(result.get("correlation_id"))  # You may need this when reporting a bug

Vários métodos estão disponíveis para aquisição interativa de token. O método a ser usado depende do tipo de aplicativo que você está criando e do fluxo de concessão de token aplicável ao seu cenário.

Aquisição interativa de token por clientes públicos

Os aplicativos cliente públicos não podem armazenar com segurança um segredo e só podem autenticar o usuário que está interagindo com o produto. O MSAL Python disponibiliza a lógica de aquisição de tokens para aplicativos públicos por meio de PublicClientApplication. Veja a seguir os diferentes métodos disponíveis para aplicativos cliente públicos adquirirem tokens.

Fluxo de código do dispositivo

O fluxo de código do dispositivo é usado para adquirir tokens em aplicativos executados em dispositivos que não têm acesso a um navegador da Web. Esses são aplicativos conhecidos como aplicativos sem cabeça. Esse fluxo fornece ao usuário uma URL e um código. O usuário vai para um navegador da Web em outro dispositivo, insere o código e entra. Na autenticação bem-sucedida, Microsoft Entra retorna um token para o dispositivo sem navegador.

Primeiro, você chama o initiate_device_flow método.

flow = app.initiate_device_flow(scopes=config["scope"])
if "user_code" not in flow:
    raise ValueError(
        "Fail to create device flow. Err: %s" % json.dumps(flow, indent=4))

print(flow["message"])
sys.stdout.flush()  # Some terminal needs this to ensure the message is shown

# Ideally you should wait here, in order to save some unnecessary polling
# input("Press Enter after signing in from another device to proceed, CTRL+C to abort.")

Em seguida, você passa o objeto de dicionário de fluxo para o acquire_token_by_device_flow método para obter o token. Por padrão, esse método bloqueia o thread atual. Você pode seguir estas instruções para reduzir o tempo de bloco ou até mesmo desativar o comportamento de bloqueio e continuar chamando acquire_token_by_device_flow em seu próprio loop personalizado.

result = app.acquire_token_by_device_flow(flow)

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Uma resposta bem-sucedida é um dicionário com uma chave access_token.

Adquirir token de forma interativa

MSAL Python também oferece a capacidade de os aplicativos cliente público (desktop e dispositivos móveis) obterem tokens em nome do usuário. O usuário entra por meio da URL de solicitação de autorização por meio de um navegador da Web. Defina o URI de redirecionamento do seu aplicativo como http://localhost no centro de administração do Microsoft Entra, no registro do seu aplicativo. Se você optar por usar o broker durante a criação de PublicClientApplication, seu aplicativo também precisará registrar ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID como um URI de redirecionamento.

result = app.acquire_token_interactive(  # It automatically provides PKCE protection
    scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Nome de usuário e senha

Não recomendamos usar essa abordagem. Também é possível obter um token com um nome de usuário e senha. O Python MSAL fornece o acquire_token_by_username_password método para esse caso de uso. Não é recomendável porque o aplicativo solicitará diretamente a senha de um usuário, o que é um padrão inseguro.

Há fluxos mais seguros que você pode usar. Saiba mais nas diretrizes de fluxo de autenticação de nome de usuário e senha .

result = app.acquire_token_by_username_password(
    username=config["username"], password=config["password"], scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))  

Obtenção interativa de token para clientes confidenciais

Aplicativos cliente confidenciais podem armazenar com segurança um segredo e podem autenticar em nome de um aplicativo, bem como em nome de um determinado usuário. O Python MSAL fornece aos desenvolvedores vários métodos para adquirir tokens ao desenvolverConfidentialClientApplication.

Obter token para cliente

Adquira o token como o próprio aplicativo usando credenciais de cliente e não para um usuário. Por exemplo, isso pode ser usado em aplicativos que processam usuários em lotes e não em um usuário específico, como ferramentas de sincronização. A MSAL Python fornece o acquire_token_for_client método para fazer isso. Como a MSAL Python 1.23, esse método procura automaticamente o token do cache e envia apenas a solicitação para o provedor de identidade quando o cache falha.

result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    access_token = result["access_token"]
else:
    print(result.get("error"))    

Obter token em nome de

No caso de aplicativos web ou APIs web que chamam outra API web downstream em nome do usuário, use o fluxo On-Behalf-Of para obter um token com base em uma asserção do usuário. Por exemplo, SAML e JWT. O aplicativo atual é um serviço de camada intermediária que foi chamado com um token que representa um usuário final. O aplicativo atual pode usar esse token, também conhecido como declaração de usuário, para solicitar outro token para acessar a API Web downstream em nome desse usuário. O aplicativo de camada intermediária não tem interação do usuário para obter consentimento. Para obter informações sobre como obter consentimento antecipadamente para seu aplicativo de camada intermediária, consulte a documentação.

Aqui está um exemplo de código que adquire um token de acesso usando o acquire_token_on_behalf_of método.

def get(self, request): # a web service endpoint receiving a request
    
    scopes = ["your-scopes"]
    downstream_api = "https://your-downstreamapi.com/resource" #your downstream API resource endpoint
    current_access_token = request.headers.get("Authorization", None)
    
    # initialize the app
    app = msal.ConfidentialClientApplication(...) # refer to initialization of the app documentation

    #acquire token on behalf of the user that called this API
    downstream_api_access_token = app.acquire_token_on_behalf_of(
        user_assertion=current_app_access_token.split(' ')[1],
        scopes=_scopes
    )

    if "access_token" in result:
        access_token = result["access_token"]
        # use access_token to call dowstream API e.g
        requests.get(downstream_api, headers={'Authorization': f'Bearer {downstream_api_access_token}'})
    else:
        print(result.get("error")) 

Obter token por fluxo de código de autorização

Para aplicativos Web que se autenticam no nome de um usuário, adquira tokens por meio do código de autorização depois de permitir que o usuário entre por meio da URL da solicitação de autorização. Normalmente, esse é o mecanismo usado por um aplicativo que permite que o usuário entre e acesse APIs Web para esse usuário específico.

Primeiro, você precisará iniciar o fluxo de código de autenticação usando o initiate_auth_code_flow. Esse método usa entre outros parâmetros um URI de redirecionamento e uma cadeia de caracteres de estado. O valor do parâmetro de estado também está incluído na resposta do token. Se esse valor estiver ausente, a MSAL Python gerará automaticamente uma internamente. O URI de redirecionamento fornecido deve corresponder ao URI de redirecionamento registrado no centro de administração do Microsoft Entra. Esse método retorna o fluxo de código de autenticação que é um dicionário que contém auth_uri e state. O auth_uri é a URL que o usuário precisa acessar para fazer login.

flow = app.initiate_auth_code_flow(
    scopes=config["scope"], redirect_uri=config["redirect_uri"], state="your-state-value")

if "error" in flow:
    print(flow.get("error"))

# Save the response somewhere e.g in session
session["auth_flow"] = flow

# At this point, the app should guide the user to visit the auth ur (session["auth_flow"]["auth_uri"])

A resposta obtida ao visitar os endpoints do URI de autenticação é usada no método acquire_token_by_auth_code_flow. O estado é um identificador exclusivo que você pode usar para verificar a resposta do servidor de autorização. O usuário deve consentir com os escopos solicitados durante o login.

# The uth_response value from visiting the auth_uri endpoint is passed as a query string
# You can change this by passing a value to the response_mode in the initiate_auth_code_flow method
try:
    result = app.acquire_token_by_auth_code_flow(session.get("flow", {}), auth_response)
    
    if "access_token" in result:
        access_token = result["access_token"]
    else:
        print(result.get("error"))
except ValueError:  # Usually caused by CSRF
    pass  # Simply ignore them

Cache de tokens do MSAL para Python

Tanto os aplicativos cliente públicos quanto os confidenciais oferecem suporte ao cache de tokens, gerenciado diretamente pelo MSAL Python. Os aplicativos devem tentar obter um token do cache primeiro antes de depender de qualquer outro meio. Para obter mais informações, consulte o padrão de aquisição de token recomendado.

Para poder persistir o cache, os desenvolvedores precisam configurar a lógica de serialização do cache de token .