Adquira tokens para chamar uma API da Web usando um aplicativo daemon

Depois de criar um aplicativo cliente confidencial, você pode adquirir um token para o aplicativo chamando AcquireTokenForClient, passando o escopo e, opcionalmente, forçando uma atualização do token.

Escopos a solicitar

O escopo para solicitar um fluxo de credenciais de cliente é o nome do recurso seguido por /.default. Essa notação informa ao Microsoft Entra ID para usar as permissões de nível de aplicativo declaradas estaticamente durante o registro do aplicativo. Além disso, essas permissões de API devem ser concedidas por um administrador de locatário.

.NET

Aqui está um exemplo de definição dos escopos para a API da Web como parte da configuração em um arquivo de appsettings.json. Este exemplo é retirado do exemplo de código de daemon do console .NET no GitHub.

{
    "AzureAd": {
        // Same AzureAd section as before.
    },

    "MyWebApi": {
        "BaseUrl": "https://localhost:44372/",
        "RelativePath": "api/TodoList",
        "RequestAppToken": true,
        "Scopes": [ "[Enter here the scopes for your web API]" ]
    }
}

Java

final static String GRAPH_DEFAULT_SCOPE = "https://graph.microsoft.com/.default";

Node.js

const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '.default'], // e.g. 'https://graph.microsoft.com/.default'
};

Python

No MSAL Python, o arquivo de configuração se parece com este trecho de código:

{
    "scope": ["https://graph.microsoft.com/.default"],
}

.NET (nível baixo)

ResourceId = "someAppIDURI";
var scopes = new [] {  ResourceId+"/.default"};

Recursos do Azure AD (v1.0)

O escopo usado para credenciais de cliente deve ser sempre o ID do recurso seguido por /.default.

Importante

Quando o MSAL solicita um token de acesso para um recurso que aceita um token de acesso da versão 1.0, o ID do Microsoft Entra analisa o público desejado a partir do escopo solicitado, pegando tudo antes da última barra e usando-o como o identificador de recurso. Portanto, se, como o Banco de Dados SQL do Azure (https://database.windows.net), o recurso espera uma audiência que termina com uma barra (para o Banco de Dados SQL do Azure, https://database.windows.net/), você precisará solicitar um escopo de https://database.windows.net//.default. (Observe a barra dupla.) Ver também MSAL.NET edição #747: Resource url's trailing slash is omitted, which caused sql auth failure.

AcquireTokenForClient API

Para adquirir um token para o aplicativo, use AcquireTokenForClient ou seu equivalente, dependendo da plataforma.

.NET

Com Microsoft.Identity.Web, você não precisa adquirir um token. Você pode usar APIs de nível superior, como você vê em Chamando uma API da Web de um aplicativo daemon. Se, no entanto, você estiver usando um SDK que exija um token, o trecho de código a seguir mostra como obter esse token.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

// In the Program.cs, acquire a token for your downstream API

var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
ITokenAcquirer acquirer = tokenAcquirerFactory.GetTokenAcquirer();
AcquireTokenResult tokenResult = await acquirer.GetTokenForUserAsync(new[] { "https://graph.microsoft.com/.default" });
string accessToken = tokenResult.AccessToken;

Java

Este código é extraído dos exemplos de desenvolvimento do MSAL Java.

private static IAuthenticationResult acquireToken() throws Exception {

     // Load token cache from file and initialize token cache aspect. The token cache will have
     // dummy data, so the acquireTokenSilently call will fail.
     TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

     IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);
     ConfidentialClientApplication cca =
             ConfidentialClientApplication
                     .builder(CLIENT_ID, credential)
                     .authority(AUTHORITY)
                     .setTokenCacheAccessAspect(tokenCacheAspect)
                     .build();

     IAuthenticationResult result;
     try {
         SilentParameters silentParameters =
                 SilentParameters
                         .builder(SCOPE)
                         .build();

         // try to acquire token silently. This call will fail since the token cache does not
         // have a token for the application you are requesting an access token for
         result = cca.acquireTokenSilently(silentParameters).join();
     } catch (Exception ex) {
         if (ex.getCause() instanceof MsalException) {

             ClientCredentialParameters parameters =
                     ClientCredentialParameters
                             .builder(SCOPE)
                             .build();

             // Try to acquire a token. If successful, you should see
             // the token information printed out to console
             result = cca.acquireToken(parameters).join();
         } else {
             // Handle other exceptions accordingly
             throw ex;
         }
     }
     return result;
 }

Node.js

O trecho de código a seguir ilustra a aquisição de token em um aplicativo cliente confidencial do nó MSAL:

try {
    const authResponse = await cca.acquireTokenByClientCredential(tokenRequest);
    console.log(authResponse.accessToken) // display access token
} catch (error) {
    console.log(error);
}

Python

# The pattern to acquire a token looks like this.
result = None

# First, the code looks up a token from the cache.
# Because we're looking for a token for the current app, not for a user,
# use None for the account parameter.
result = app.acquire_token_silent(config["scope"], account=None)

if not result:
    logging.info("No suitable token exists in cache. Let's get a new one from Azure AD.")
    result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    # Call a protected API with the access token.
    print(result["token_type"])
else:
    print(result.get("error"))
    print(result.get("error_description"))
    print(result.get("correlation_id"))  # You might need this when reporting a bug.

.NET (nível baixo)

using Microsoft.Identity.Client;

// With client credentials flows, the scope is always of the shape "resource/.default" because the
// application permissions need to be set statically (in the portal or by PowerShell), and then granted by
// a tenant administrator.
string[] scopes = new string[] { "https://graph.microsoft.com/.default" };

AuthenticationResult result = null;
try
{
 result = await app.AcquireTokenForClient(scopes)
                  .ExecuteAsync();
}
catch (MsalUiRequiredException ex)
{
    // The application doesn't have sufficient permissions.
    // - Did you declare enough app permissions during app creation?
    // - Did the tenant admin grant permissions to the application?
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
    // Invalid scope. The scope has to be in the form "https://resourceurl/.default"
    // Mitigation: Change the scope to be as expected.
}

AcquireTokenForClient usa o cache de token de aplicativo

No MSAL.NET, AcquireTokenForClient usa o cache de token de aplicativo. (Todos os outros AcquireToken XX métodos usam o cache de token de usuário.) Não ligue AcquireTokenSilent antes de chamar AcquireTokenForClient, porque AcquireTokenSilent usa o cache de token de usuário. AcquireTokenForClient verifica o próprio cache de token do aplicativo e o atualiza.

Protocolo

Se você ainda não tem uma biblioteca para o idioma escolhido, convém usar o protocolo diretamente:

Primeiro caso: acessar a solicitação de token usando um segredo compartilhado

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=A1b-C2d_E3f.H4i,J5k?L6m!N7o-P8q_R9s.T0u
&grant_type=client_credentials

Segundo caso: acessar a solicitação de token usando um certificado

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=aaaaaaaa-0b0b-...
&grant_type=client_credentials

Para obter mais informações, consulte a documentação do protocolo: plataforma de identidade da Microsoft e o fluxo de credenciais do cliente OAuth 2.0.

Resolução de Problemas

Você usou o escopo resource/.default?

Se você receber uma mensagem de erro informando que usou um escopo inválido, provavelmente não usou o resource/.default escopo.

Esqueceu-se de dar o consentimento do administrador? Os aplicativos Daemon precisam disso!

Se você receber um erro de privilégios insuficientes para concluir a operação ao chamar a API, o administrador do locatário precisará conceder permissões ao aplicativo.

Se você não conceder consentimento de administrador para seu aplicativo, você encontrará o seguinte erro:

Failed to call the web API: Forbidden
Content: {
  "error": {
    "code": "Authorization_RequestDenied",
    "message": "Insufficient privileges to complete the operation.",
    "innerError": {
      "request-id": "<guid>",
      "date": "<date>"
    }
  }
}

Selecione uma das seguintes opções, dependendo da função.

Administrador de locatário global

Para um administrador de locatário global, vá para Aplicativos corporativos no centro de administração do Microsoft Entra. Selecione o registro do aplicativo e selecione Permissões na seção Segurança do painel esquerdo. Em seguida, selecione o botão grande rotulado Conceder consentimento de administrador para {Nome do locatário} (onde {Nome do locatário} é o nome do diretório).

Usuário padrão

Para um usuário padrão do seu locatário, peça a um Administrador Global que conceda consentimento de administrador para o aplicativo. Para fazer isso, forneça a seguinte URL para o administrador:

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

No URL:

• Substitua Enter_the_Tenant_Id_Here pelo ID do locatário ou nome do locatário (por exemplo, contoso.microsoft.com).
• Enter_the_Application_Id_Here é o ID do aplicativo (cliente) para o aplicativo registrado.

O erro AADSTS50011: No reply address is registered for the application pode ser exibido depois que você concede consentimento para o aplicativo usando a URL anterior. Este erro ocorre porque o aplicativo e a URL não têm um URI de redirecionamento. Isto pode ser ignorado.

Você está chamando sua própria API?

Se seu aplicativo daemon chamar sua própria API da Web e você não conseguir adicionar uma permissão de aplicativo ao registro do aplicativo do daemon, será necessário Adicionar funções do aplicativo ao registro do aplicativo da API da Web.

Próximos passos

.NET

Passe para o próximo artigo neste cenário, Chamando uma API da Web.

Java

Passe para o próximo artigo neste cenário, Chamando uma API da Web.

Node.js

Passe para o próximo artigo neste cenário, Chamando uma API da Web.

Python

Passe para o próximo artigo neste cenário, Chamando uma API da Web.

.NET de baixo nível

Passe para o próximo artigo neste cenário, Chamando uma API da Web.