Sumber daya dan cakupan

platform identitas Microsoft menggunakan model yang berfokus pada cakupan untuk mengakses sumber daya. Di sini, sumber daya mengacu pada aplikasi apa pun yang dapat menjadi penerima Token Akses (seperti MS Graph API atau API web Anda sendiri), dan cakupan (alias "izin") mengacu pada aspek sumber daya apa pun yang diberikan Token Akses.

Permintaan Token Akses dalam MSAL.js dirancang untuk bersifat per-sumber-daya-per-cakupan. Ini berarti bahwa Token Akses yang diminta untuk sumber daya A dengan cakupan scp1:

  • tidak dapat digunakan untuk mengakses sumber daya A dengan cakupan scp2, dan,
  • tidak dapat digunakan untuk mengakses sumber daya B dari cakupan apa pun.

Penerima yang dituju untuk Access Token diwakili oleh klaim aud; jika nilai untuk klaim aud tidak cocok dengan resource APP ID URI, token tersebut harus dianggap tidak valid. Demikian pula, izin yang diberikan oleh Token Akses direpresentasikan oleh klaim scp. Lihat Klaim Token Akses untuk informasi selengkapnya.

Cakupan bawaan

Secara bawaan, MSAL.js akan menambahkan cakupan openid, profile, dan offline_access ke setiap permintaan. Cakupan ini diperlukan untuk menerima token refresh dan klaim token id yang digunakan untuk mengisi objek akun dengan informasi pengguna.

Bekerja dengan beberapa sumber daya

Ketika Anda harus mengakses beberapa sumber daya, mulai permintaan token terpisah untuk masing-masing:

// "User.Read" stands as shorthand for "graph.microsoft.com/User.Read"
const graphToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read" ]
});
const customApiToken = await msalInstance.acquireTokenSilent({
     scopes: [ "api://<myCustomApiClientId>/My.Scope" ]
});

Perlu diingat bahwa Anda dapat meminta beberapa cakupan untuk sumber daya yang sama (misalnya User.Read, User.Write dan Calendar.Read untuk MS Graph API).

const graphToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read", "User.Write", "Calendar.Read" ] // all MS Graph API scopes
});

Jika Anda secara keliru meneruskan beberapa sumber daya dalam permintaan token Anda, token yang akan Anda terima hanya akan dikeluarkan untuk sumber daya pertama.

// you will only receive a token for MS GRAPH API's "User.Read" scope here
const myToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read", "api://<myCustomApiClientId>/My.Scope" ]
});

Dalam Microsoft Entra ID, cakupan (izin) yang diatur langsung pada pendaftaran aplikasi disebut cakupan statis. Cakupan lain yang hanya ditentukan dalam kode disebut cakupan dinamis. Ini memiliki implikasi pada metode login (yaitu loginPopup, loginRedirect) dan acquireToken (yaitu acquireTokenPopup, acquireTokenRedirect, acquireTokenSilent) metode MSAL.js. Pertimbangkan:

 const loginRequest = {
      scopes: [ "openid", "profile", "User.Read" ]
 };
 const tokenRequest = {
      scopes: [ "Mail.Read" ]
 };
 // will return an ID Token and an Access Token with scopes: "openid", "profile" and "User.Read"
 msalInstance.loginPopup(loginRequest);
 // will fail and fallback to an interactive method prompting a consent screen
 // after consent, the received token will be issued for "openid", "profile" ,"User.Read" and "Mail.Read" combined
 msalInstance.acquireTokenSilent(tokenRequest);

Dalam cuplikan kode di atas, pengguna akan dimintai persetujuan setelah mereka mengautentikasi dan menerima Token ID dan Token Akses dengan cakupan User.Read. Nantinya, jika mereka meminta Token Akses untuk User.Read, mereka tidak akan dimintai persetujuan lagi (dengan kata lain, mereka dapat memperoleh token secara diam-diam).

Di sisi lain, pengguna tidak menyetujui Mail.Read pada tahap autentikasi, oleh karena itu, akan dimintai persetujuan saat meminta Token Akses untuk Mail.Read cakupan. Token yang diterima akan berisi semua cakupan yang disetujui sebelumnya (untuk sumber daya tertentu), oleh karena itu istilah persetujuan inkremental.

Pertimbangkan kasus yang sedikit berbeda:

 const loginRequest = {
      scopes: [ "openid", "profile", "User.Read" ],
      extraScopesToConsent: [ "api://<myCustomApiClientId>/My.Scope"]
 };
 const tokenRequest = {
      scopes: [ "Mail.Read" ]
 };
 const anotherTokenRequest = {
      scopes: [ "api://<myCustomApiClientId>/My.Scope" ]
 }
 // will return an ID Token and an Access Token with scopes: "openid", "profile" and "User.Read"
 msalInstance.loginPopup(loginRequest);
 // will fail with InteractionRequiredError due to lack of consent for "Mail.Read" scope. You should fallback to an interactive method in this case.
 msalInstance.acquireTokenSilent(tokenRequest);
 // will succeed and return an Access Token with scope "api://<myCustomApiClientId>/My.Scope"
 msalInstance.acquireTokenSilent(anotherTokenRequest);

Dalam cuplikan kode di atas, meskipun pengguna menyetujui cakupan User.Read dan api://<myCustomApiClientId>/My.Scope, mereka hanya akan menerima Token Akses untuk MS Graph API, sesuai dengan prinsip per-resource-per-scope. Namun, karena mereka sudah menyetujui api://<myCustomApiClientId>/My.Scope, mereka dapat memperoleh Token Akses untuk sumber daya/cakupan tersebut secara diam-diam nanti.

Dalam Microsoft Entra ID, persetujuan hidup di luar masa pakai aplikasi. Ini berarti bahwa, ketika Anda meminta Token Akses untuk sumber daya, semua cakupan yang sebelumnya telah Anda setujui untuk sumber daya tersebut akan dikembalikan, terlepas dari cakupan apa yang diminta pada saat itu. Dengan kata lain, jika Anda menyetujui User.Read dan Mail.Read hari ini lalu menjalankan instans baru aplikasi Anda besok yang meminta Token Akses hanya untuk User.Read, Anda tetap akan menerima token yang diterbitkan untuk keduanyaUser.Read dan Mail.Read. Untuk informasi selengkapnya, lihat Izin dan Persetujuan.

  • Last updated on