Aplikasi desktop yang memanggil API web: Panggil API web

Setelah memiliki token, Anda dapat memanggil API web yang dilindungi.

Memanggil API web

.NET

Properti AuthenticationResult di MSAL.NET

Metode untuk memperoleh token menampilkan AuthenticationResult. Untuk metode asinkron, Task<AuthenticationResult> ditampilkan.

Dalam MSAL.NET, AuthenticationResult mengekspos:

• AccessToken untuk API web untuk mengakses sumber daya. Parameter ini adalah string, biasanya JWT berkode Base-64. Klien tidak boleh melihat ke dalam token akses. Formatnya tidak dijamin tetap stabil, dan dapat dienkripsi untuk sumber daya. Menulis kode yang tergantung pada konten token akses pada klien adalah salah satu sumber kesalahan terbesar dan jeda logika klien. Untuk mengetahui informasi selengkapnya, lihat Token akses.
• IdToken untuk pengguna. Parameter ini adalah JWT yang dikodekan. Untuk mengetahui informasi selengkapnya, lihat Token ID.
• ExpiresOn memberi tahu tanggal dan waktu saat token kedaluwarsa.
• TenantId berisi penyewa tempat pengguna ditemukan. Untuk pengguna tamu dalam skenario Microsoft Entra B2B, ID penyewa adalah penyewa tamu, bukan penyewa unik. Saat token dikirim untuk pengguna, AuthenticationResult juga berisi informasi tentang pengguna ini. Untuk alur klien rahasia yang mana token diminta tanpa pengguna untuk aplikasi, informasi pengguna ini adalah null.
• Scopes yang tokennya dikeluarkan.
• ID unik untuk pengguna.

IAccount

MSAL.NET mendefinisikan gagasan akun melalui antarmuka IAccount. Perubahan melanggar ini memberikan semantik yang tepat. Pengguna yang sama dapat memiliki beberapa akun, di direktori Microsoft Entra yang berbeda. MSAL.NET juga memberikan informasi yang lebih baik dalam skenario tamu, karena informasi akun beranda disediakan. Diagram berikut menunjukkan struktur antarmuka IAccount.

Kelas AccountId mengidentifikasi akun di penyewa tertentu dengan properti yang ditunjukkan dalam tabel berikut.

Properti	Deskripsi
TenantId	Representasi string untuk GUID, yang merupakan ID penyewa tempat akun berada.
ObjectId	Representasi string untuk GUID, yang merupakan ID pengguna yang memiliki akun di penyewa.
Identifier	Pengidentifikasi unik untuk akun. Identifier adalah perangkaian ObjectId dan TenantId yang dipisahkan oleh koma. Ini bukan Base 64 yang dikodekan.

Antarmuka IAccount mewakili informasi tentang satu akun. Pengguna yang sama dapat tersedia di penyewa yang berbeda, yang berarti bahwa pengguna dapat memiliki beberapa akun. Anggotanya ditampilkan dalam tabel berikut.

Properti	Deskripsi
Username	String yang berisi nilai yang dapat ditampilkan dalam format UserPrincipalName (UPN), misalnya, john.doe@contoso.com. String ini bisa null, tidak seperti HomeAccountId dan HomeAccountId.Identifier, yang tidak akan null. Properti ini menggantikan properti DisplayableId dari IUser pada versi MSAL.NET sebelumnya.
Environment	String yang berisi penyedia identitas untuk akun ini, misalnya, login.microsoftonline.com. Properti ini menggantikan properti IdentityProvider dari IUser, kecuali IdentityProvider juga memiliki informasi tentang penyewa, selain lingkungan cloud. Di sini, nilainya hanya berupa host.
HomeAccountId	ID akun untuk akun rumah bagi pengguna. Properti ini secara unik mengidentifikasi pengguna di seluruh penyewa Microsoft Entra.

Gunakan token untuk memanggil API yang dilindungi

Setelah AuthenticationResult ditampilkan oleh MSAL di result, tambahkan ke header otorisasi HTTP sebelum Anda melakukan panggilan untuk mengakses API web yang dilindungi.

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);
...
}

Java

HttpURLConnection conn = (HttpURLConnection) url.openConnection();

PublicClientApplication pca = PublicClientApplication.builder(clientId)
        .authority(authority)
        .build();

// Acquire a token, acquireTokenHelper would call publicClientApplication's acquireTokenSilently then acquireToken
// see https://github.com/Azure-Samples/ms-identity-java-desktop for a full example
IAuthenticationResult authenticationResult = acquireTokenHelper(pca);

// Set the appropriate header fields in the request header.
conn.setRequestProperty("Authorization", "Bearer " + authenticationResult.accessToken);
conn.setRequestProperty("Accept", "application/json");

String response = HttpClientHelper.getResponseStringFromConn(conn);

int responseCode = conn.getResponseCode();
if(responseCode != HttpURLConnection.HTTP_OK) {
    throw new IOException(response);
}

JSONObject responseObject = HttpClientHelper.processResponse(responseCode, response);

MacOS

Memanggil API web di MSAL untuk iOS dan macOS

Metode untuk memperoleh token menghasilkan objek MSALResult. MSALResult mengekspos accessToken properti yang dapat digunakan untuk memanggil API web. Tambahkan token akses ke header otorisasi HTTP sebelum Anda melakukan panggilan untuk mengakses API web yang dilindungi.

Objective-C:

NSMutableURLRequest *urlRequest = [NSMutableURLRequest new];
urlRequest.URL = [NSURL URLWithString:"https://contoso.api.com"];
urlRequest.HTTPMethod = @"GET";
urlRequest.allHTTPHeaderFields = @{ @"Authorization" : [NSString stringWithFormat:@"Bearer %@", accessToken] };

NSURLSessionDataTask *task =
[[NSURLSession sharedSession] dataTaskWithRequest:urlRequest
     completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {}];
[task resume];

Swift:

let urlRequest = NSMutableURLRequest()
urlRequest.url = URL(string: "https://contoso.api.com")!
urlRequest.httpMethod = "GET"
urlRequest.allHTTPHeaderFields = [ "Authorization" : "Bearer \(accessToken)" ]

let task = URLSession.shared.dataTask(with: urlRequest as URLRequest) { (data: Data?, response: URLResponse?, error: Error?) in }
task.resume()

Memanggil beberapa API: Persetujuan inkremental dan Akses Bersyar

Untuk memanggil beberapa API pengguna yang sama, setelah Anda mendapatkan token API pertama, panggil AcquireTokenSilent. Anda akan mendapatkan token untuk API lain secara senyap sebagian besar waktu.

var result = await app.AcquireTokenXX("scopeApi1")
                      .ExecuteAsync();

result = await app.AcquireTokenSilent("scopeApi2")
                  .ExecuteAsync();

Interaksi diperlukan ketika:

• Pengguna menyetujui API pertama tetapi sekarang perlu menyetujui lebih banyak cakupan. Persetujuan seperti ini dikenal sebagai persetujuan bertahap.
• API pertama tidak mengharuskan autentikasi multifaktor, namun setelah itu iya.

var result = await app.AcquireTokenXX("scopeApi1")
                      .ExecuteAsync();

try
{
 result = await app.AcquireTokenSilent("scopeApi2")
                  .ExecuteAsync();
}
catch(MsalUiRequiredException ex)
{
 result = await app.AcquireTokenInteractive("scopeApi2")
                  .WithClaims(ex.Claims)
                  .ExecuteAsync();
}

Node.js

Menggunakan klien HTTP seperti Axios, panggil URI titik akhir API dengan token akses sebagai token pembawa otorisasi.

const axios = require('axios');

async function callEndpointWithToken(endpoint, accessToken) {
    const options = {
        headers: {
            Authorization: `Bearer ${accessToken}`
        }
    };

    console.log('Request made at: ' + new Date().toString());

    const response = await axios.default.get(endpoint, options);

    return response.data;
}

Python

endpoint = "url to the API"
http_headers = {'Authorization': 'Bearer ' + result['access_token'],
                'Accept': 'application/json',
                'Content-Type': 'application/json'}
data = requests.get(endpoint, headers=http_headers, stream=False).json()

Langkah berikutnya

Beralih ke artikel berikutnya dalam skenario ini, Beralih ke produksi.