Memperoleh token untuk memanggil API web menggunakan aplikasi daemon

Setelah Anda membuat aplikasi klien rahasia, Anda dapat memperoleh token untuk aplikasi dengan memanggil AcquireTokenForClient, melewati cakupan, dan secara opsional memaksa refresh token.

Cakupan untuk permintaan

Cakupan untuk meminta aliran info masuk klien adalah nama sumber daya yang diikuti oleh dengan /.default. Notasi ini memberi tahu Microsoft Entra ID untuk menggunakan izin tingkat aplikasi yang dinyatakan secara statis selama pendaftaran aplikasi. Selain itu, izin API berikut harus diberikan oleh administrator penyewa.

.NET

Berikut adalah contoh menentukan cakupan untuk API web sebagai bagian dari konfigurasi dalam file appsettings.json. Contoh ini diambil dari sampel kode daemon konsol .NET di 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

Di Python MSAL, file konfigurasi terlihat seperti cuplikan kode ini:

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

.NET (tingkat rendah)

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

Sumber daya Microsoft Azure AD (v1.0)

Cakupan yang digunakan untuk info masuk klien harus selalu menjadi ID sumber daya diikuti oleh /.default.

Penting

Ketika MSAL meminta token akses untuk sumber daya yang menerima token akses versi 1.0, ID Microsoft Entra mengurai audiens yang diinginkan dari cakupan yang diminta dengan mengambil semuanya sebelum garis miring terakhir dan menggunakannya sebagai pengidentifikasi sumber daya. Jika, seperti Azure SQL Database (https://database.windows.net), sumber daya mengharapkan audiens yang diakhiri dengan garis miring (untuk Azure SQL Database, https://database.windows.net/), Anda harus meminta cakupan https://database.windows.net//.default. (Perhatikan garis miring ganda.) Lihat juga masalah MSAL.NET #747: Resource url's trailing slash is omitted, which caused sql auth failure.

API AcquireTokenForClient

Untuk memperoleh token untuk aplikasi, gunakan AcquireTokenForClient atau yang setara, tergantung pada platform.

.NET

Dengan Microsoft.Identity.Web, Anda tidak perlu memperoleh token. Anda dapat menggunakan API tingkat yang lebih tinggi, seperti yang Anda lihat di Memanggil API web dari aplikasi daemon. Namun, jika Anda menggunakan SDK yang memerlukan token, cuplikan kode berikut menunjukkan cara mendapatkan token ini.

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

Kode ini diekstrak dari sampel MSAL Java dev.

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

Cuplikan kode berikut menggambarkan akuisisi token dalam aplikasi klien rahasia MSAL Node:

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 (tingkat rendah)

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 menggunakan cache token aplikasi

Di MSAL.NET, AcquireTokenForClient menggunakan cache token aplikasi. (Semua metode AcquireTokenXX lainnya menggunakan cache token pengguna.) Jangan memanggil AcquireTokenSilent sebelum Anda memanggil AcquireTokenForClient, karena AcquireTokenSilent menggunakan cache token pengguna. AcquireTokenForClient memeriksa cache token aplikasi itu sendiri dan memperbaruinya.

Protokol

Jika Anda belum memiliki pustaka untuk bahasa yang dipilih, Anda mungkin ingin menggunakan protokol secara langsung:

Kasus pertama: Mengakses permintaan token dengan menggunakan rahasia bersama

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

Kasus kedua: Mengakses permintaan token dengan menggunakan sertifikat

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

Untuk informasi selengkapnya, lihat dokumentasi protokol: Platform identitas Microsoft dan alur kredensial klien OAuth 2.0.

Pemecahan Masalah

Apakah Anda menggunakan cakupan resource/.default?

Jika Anda mendapatkan pesan kesalahan yang memberi tahu bahwa Anda menggunakan cakupan yang tidak valid, Anda mungkin tidak menggunakan cakupan resource/.default.

Apakah Anda lupa memberikan persetujuan admin? Aplikasi Daemon membutuhkannya!

Jika Anda mendapatkan kesalahan hak istimewa yang tidak mencukupi untuk memanggil API, administrator penyewa perlu memberikan izin ke aplikasi.

Jika Anda tidak memberikan persetujuan admin untuk aplikasi, Anda akan mengalami kesalahan berikut:

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

Pilih salah satu opsi berikut, tergantung pada perannya.

Administrator penyewa global

Untuk administrator penyewa global, buka Aplikasi perusahaan di pusat admin Microsoft Entra. Pilih pendaftaran aplikasi, dan pilih Izin dari bagian Keamanan di panel kiri. Kemudian pilih tombol besar berlabel Berikan persetujuan admin untuk {Tenant Name} (di mana {Tenant Name} adalah nama direktori).

Pengguna standar

Untuk pengguna standar penyewa Anda, minta Administrator Global untuk memberikan persetujuan admin ke aplikasi. Untuk melakukan ini, berikan URL berikut kepada administrator:

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

Di URL:

• Ganti Enter_the_Tenant_Id_Here dengan ID penyewa atau nama penyewa (misalnya, contoso.microsoft.com).
• Enter_the_Application_Id_Here adalah ID aplikasi (klien) untuk aplikasi terdaftar.

AADSTS50011: No reply address is registered for the application Kesalahan dapat ditampilkan setelah Anda memberikan persetujuan ke aplikasi dengan menggunakan URL sebelumnya. Kesalahan ini terjadi karena aplikasi dan URL tidak memiliki URI pengalihan. Ini dapat diabaikan.

Apakah Anda memanggil API Anda sendiri?

Jika aplikasi daemon Anda memanggil API web Anda sendiri dan Anda tidak dapat menambahkan izin aplikasi ke pendaftaran aplikasi daemon, Anda perlu Menambahkan peran aplikasi ke pendaftaran aplikasi API web.

Langkah berikutnya

.NET

Lanjut ke artikel berikutnya dalam skenario ini, Memanggil API web.

Java

Lanjut ke artikel berikutnya dalam skenario ini, Memanggil API web.

Node.js

Lanjut ke artikel berikutnya dalam skenario ini, Memanggil API web.

Python

Lanjut ke artikel berikutnya dalam skenario ini, Memanggil API web.

Tingkat rendah .NET

Lanjut ke artikel berikutnya dalam skenario ini, Memanggil API web.