Autentikasi dan otorisasi ke Spatial Anchors Azure

Dalam artikel ini, Anda akan mempelajari berbagai cara untuk mengautentikasi ke Spatial Anchors Azure dari aplikasi atau layanan web. Anda juga akan mempelajari cara menggunakan kontrol akses berbasis peran Azure (Azure RBAC) di ID Microsoft Entra untuk mengontrol akses ke akun Spatial Anchors Anda.

Peringatan

Kami menyarankan Anda menggunakan kunci akun untuk onboarding cepat, tetapi hanya selama pengembangan/prototipe. Kami tidak menyarankan Anda mengirimkan aplikasi ke produksi dengan kunci akun yang disematkan di dalamnya. Sebagai gantinya, gunakan pendekatan autentikasi Microsoft Entra berbasis pengguna atau berbasis layanan yang dijelaskan berikutnya.

Gambaran Umum

Untuk mengakses akun Spatial Anchors Azure yang diberikan, klien harus terlebih dahulu mendapatkan token akses dari layanan token keamanan (STS) Azure Mixed Reality. Token yang diperoleh dari STS memiliki masa pakai 24 jam. STS berisi informasi yang digunakan layanan Spatial Anchors untuk membuat keputusan otorisasi pada akun dan memastikan bahwa hanya prinsipal yang berwenang yang dapat mengakses akun.

Token akses dapat diperoleh dengan imbalan kunci akun atau token yang dikeluarkan oleh ID Microsoft Entra.

Kunci akun memungkinkan Anda memulai dengan cepat menggunakan layanan Spatial Anchors Azure. Tetapi sebelum Menyebarkan aplikasi ke produksi, kami sarankan Anda memperbarui aplikasi untuk menggunakan autentikasi Microsoft Entra.

Anda dapat memperoleh token autentikasi Microsoft Entra dengan dua cara:

• Jika Anda membangun aplikasi perusahaan dan perusahaan Anda menggunakan ID Microsoft Entra sebagai sistem identitasnya, Anda dapat menggunakan autentikasi Microsoft Entra berbasis pengguna di aplikasi Anda. Anda kemudian memberikan akses ke akun Spatial Anchors Anda dengan menggunakan grup keamanan Microsoft Entra yang sudah ada. Anda juga dapat memberikan akses langsung ke pengguna di organisasi Anda.
• Jika tidak, kami sarankan Anda mendapatkan token Microsoft Entra dari layanan web yang mendukung aplikasi Anda. Kami menyarankan metode ini untuk aplikasi produksi karena memungkinkan Anda menghindari penyematan info masuk untuk akses ke Spatial Anchors Azure di aplikasi klien.

Kunci akun

Cara termudah untuk memulai adalah dengan menggunakan kunci akun untuk akses ke akun Spatial Anchors Azure Anda. Anda bisa mendapatkan kunci akun di portal Azure. Buka akun Anda dan pilih tab Kunci:

Dua kunci tersedia. Keduanya secara bersamaan valid untuk akses ke akun Spatial Anchors. Kami menyarankan Anda untuk secara teratur memperbarui kunci yang digunakan untuk mengakses akun. Memiliki dua kunci valid yang terpisah memungkinkan pembaruan ini tanpa waktu henti. Anda hanya perlu memperbarui kunci primer dan kunci sekunder sebagai alternatif.

SDK memiliki dukungan bawaan untuk autentikasi melalui kunci akun. Anda hanya perlu mengatur properti AccountKey pada objek cloudSession Anda:

C#

this.cloudSession.Configuration.AccountKey = @"MyAccountKey";

Objective-C

_cloudSession.configuration.accountKey = @"MyAccountKey";

Swift

_cloudSession!.configuration.accountKey = "MyAccountKey"

Java

mCloudSession.getConfiguration().setAccountKey("MyAccountKey");

C++ NDK

auto configuration = cloudSession_->Configuration();
configuration->AccountKey(R"(MyAccountKey)");

C++/WinRT

auto configuration = m_cloudSession.Configuration();
configuration.AccountKey(LR"(MyAccountKey)");

Setelah Anda mengatur properti tersebut, SDK akan menangani pertukaran kunci akun untuk token akses dan penembolokan token yang diperlukan untuk aplikasi.

Autentikasi pengguna Microsoft Entra

Untuk aplikasi yang menargetkan pengguna Microsoft Entra, kami sarankan Anda menggunakan token Microsoft Entra untuk pengguna. Anda dapat memperoleh token ini dengan menggunakan MSAL. Ikuti langkah-langkah dalam mulai cepat untuk mendaftarkan aplikasi, yang meliputi:

di portal Microsoft Azure

1. Daftarkan aplikasi Anda di ID Microsoft Entra sebagai aplikasi asli. Sebagai bagian dari pendaftaran, Anda harus menentukan apakah aplikasi harus berupa multitenant. Anda juga harus memberikan URL pengalihan yang diizinkan untuk aplikasi.

2. Buka tab Izin API.

3. Pilih Tambahkan izin.

   1. Pilih Penyedia Sumber Azure Mixed Reality pada tab API yang digunakan organisasi saya.
   2. Pilih Izin yang didelegasikan.
   3. Pilih mixedreality.signin di bawah mixedreality.
   4. Pilih Tambahkan izin.

4. Pilih Berikan perizinan admin.

5. Tetapkan peran ASA RBAC ke aplikasi atau pengguna yang ingin Anda beri akses ke sumber daya. Jika Anda ingin pengguna aplikasi Anda memiliki peran yang berbeda terhadap akun ASA, daftarkan beberapa aplikasi di ID Microsoft Entra dan tetapkan peran terpisah untuk masing-masing aplikasi. Kemudian terapkan logika otorisasi Anda untuk menggunakan peran yang tepat bagi pengguna. Untuk rincian langkah penetapan peran, lihat Menetapkan peran Azure menggunakan portal Azure.

Dalam kode Anda

1. Pastikan untuk menggunakan ID aplikasi dan mengalihkan URI aplikasi Microsoft Entra Anda sendiri untuk parameter ID klien dan RedirectUri di MSAL.
2. Atur informasi penyewa:
   1. Jika aplikasi Anda mendukung Hanya organisasi saya, ganti nilai ini dengan ID Penyewa atau Nama Penyewa. Misalnya, contoso.microsoft.com.
   2. Jika aplikasi Anda mendukung Akun di direktori organisasi mana pun, ganti nilai ini dengan Organisasi.
   3. Jika aplikasi Anda mendukung Semua pengguna akun Microsoft, ganti nilai ini dengan Umum.
3. Pada permintaan token Anda, atur cakupan ke https://sts.mixedreality.azure.com//.default. Cakupan ini akan menunjukkan kepada MICROSOFT Entra ID bahwa aplikasi Anda meminta token untuk Mixed Reality Security Token Service (STS).

Setelah Anda menyelesaikan langkah-langkah ini, aplikasi Anda harus dapat memperoleh dari MSAL token Microsoft Entra. Anda dapat mengatur token Microsoft Entra sebagai authenticationToken pada objek konfigurasi sesi cloud Anda:

C#

this.cloudSession.Configuration.AuthenticationToken = @"MyAuthenticationToken";

Objective-C

_cloudSession.configuration.authenticationToken = @"MyAuthenticationToken";

Swift

_cloudSession!.configuration.authenticationToken = "MyAuthenticationToken"

Java

mCloudSession.getConfiguration().setAuthenticationToken("MyAuthenticationToken");

C++ NDK

auto configuration = cloudSession_->Configuration();
configuration->AuthenticationToken(R"(MyAuthenticationToken)");

C++/WinRT

auto configuration = m_cloudSession.Configuration();
configuration.AuthenticationToken(LR"(MyAuthenticationToken)");

Autentikasi layanan Microsoft Entra

Untuk menyebarkan aplikasi yang menggunakan Spatial Anchors Azure untuk produksi, kami menyarankan Anda menggunakan layanan ujung belakang yang akan menengahi permintaan autentikasi. Berikut adalah ringkasan prosesnya:

Di sini, diasumsikan bahwa aplikasi Anda menggunakan mekanismenya sendiri untuk mengautentikasi ke layanan ujung belakang aplikasi. (Misalnya, akun Microsoft, PlayFab, Facebook, ID Google, atau nama pengguna dan kata sandi kustom.) Setelah pengguna Anda diautentikasi ke layanan back-end Anda, layanan tersebut dapat mengambil token Microsoft Entra, menukarnya dengan token akses untuk Azure Spatial Anchors, dan mengembalikannya kembali ke aplikasi klien Anda.

Token akses Microsoft Entra diambil melalui MSAL. Ikuti langkah-langkah di Mendaftarkan mulai cepat aplikasi, yang meliputi:

di portal Microsoft Azure

1. Daftarkan aplikasi Anda di ID Microsoft Entra:
   1. Di portal Azure, pilih ID Microsoft Entra, lalu pilih Pendaftaran aplikasi.
   2. Pilih Pendaftaran baru.
   3. Masukkan nama aplikasi Anda, pilih Aplikasi web / API sebagai jenis aplikasi, dan masukkan URL autentikasi untuk layanan. Pilih Buat.
2. Pada aplikasi, pilih Pengaturan, lalu pilih tab Sertifikat dan rahasia. Buat rahasia klien baru, pilih durasi, lalu pilih Tambahkan. Pastikan untuk menyimpan nilai rahasia. Anda harus memasukkannya ke dalam kode layanan web.
3. Tetapkan peran ASA RBAC ke aplikasi atau pengguna yang ingin Anda beri akses ke sumber daya. Jika Anda ingin pengguna aplikasi Anda memiliki peran yang berbeda terhadap akun ASA, daftarkan beberapa aplikasi di ID Microsoft Entra dan tetapkan peran terpisah untuk masing-masing aplikasi. Kemudian terapkan logika otorisasi Anda untuk menggunakan peran yang tepat bagi pengguna. Untuk rincian langkah penetapan peran, lihat Menetapkan peran Azure menggunakan portal Azure.

Dalam kode Anda

Catatan

Anda dapat menggunakan sampel layanan yang tersedia sebagai bagian dari aplikasi sampel Spatial Anchors.

1. Pastikan untuk menggunakan ID aplikasi, rahasia aplikasi, dan URI pengalihan aplikasi Microsoft Entra Anda sendiri sebagai parameter ID klien, rahasia, dan RedirectUri di MSAL.
2. Atur ID penyewa ke ID penyewa Microsoft Entra Anda sendiri dalam parameter otoritas di MSAL.
3. Pada permintaan token Anda, atur cakupan ke https://sts.mixedreality.azure.com//.default.

Setelah Anda menyelesaikan langkah-langkah ini, layanan back-end Anda dapat mengambil token Microsoft Entra. Layanan ujung belakang kemudian dapat menukarnya dengan token MR yang akan dikembalikan ke klien. Menggunakan token Microsoft Entra untuk mengambil token MR dilakukan melalui panggilan REST. Berikut ini contoh panggilan:

GET https://sts.mixedreality.azure.com/Accounts/35d830cb-f062-4062-9792-d6316039df56/token HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni<truncated>FL8Hq5aaOqZQnJr1koaQ
Host: sts.mixedreality.azure.com
Connection: Keep-Alive

HTTP/1.1 200 OK
Date: Sun, 24 Feb 2019 08:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1153
Accept: application/json
MS-CV: 05JLqWeKFkWpbdY944yl7A.0
{"AccessToken":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjI2MzYyMTk5ZTI2NjQxOGU4ZjE3MThlM2IyMThjZTIxIiwidHlwIjoiSldUIn0.eyJqdGkiOiJmMGFiNWIyMy0wMmUxLTQ1MTQtOWEzNC0xNzkzMTA1NTc4NzAiLCJjYWkiOiIzNWQ4MzBjYi1mMDYyLTQwNjItOTc5Mi1kNjMxNjAzOWRmNTYiLCJ0aWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJhaWQiOiIzNWQ4MzBjYi1mMDYyLTQwNjItOTc5Mi1kNjMxNjAzOWRmNTYiLCJhYW8iOi0xLCJhcHIiOiJlYXN0dXMyIiwicmlkIjoiL3N1YnNjcmlwdGlvbnMvNzIzOTdlN2EtNzA4NC00ODJhLTg3MzktNjM5Y2RmNTMxNTI0L3Jlc291cmNlR3JvdXBzL3NhbXBsZV9yZXNvdXJjZV9ncm91cC9wcm92aWRlcnMvTWljcm9zb2Z0Lk1peGVkUmVhbGl0eS9TcGF0aWFsQW5jaG9yc0FjY291bnRzL2RlbW9fYWNjb3VudCIsIm5iZiI6MTU0NDU0NzkwMywiZXhwIjoxNTQ0NjM0MzAzLCJpYXQiOjE1NDQ1NDc5MDMsImlzcyI6Imh0dHBzOi8vbXJjLWF1dGgtcHJvZC50cmFmZmljbWFuYWdlci5uZXQvIiwiYXVkIjoiaHR0cHM6Ly9tcmMtYW5jaG9yLXByb2QudHJhZmZpY21hbmFnZXIubmV0LyJ9.BFdyCX9UJj0i4W3OudmNUiuaGgVrlPasNM-5VqXdNAExD8acFJnHdvSf6uLiVvPiQwY1atYyPbOnLYhEbIcxNX-YAfZ-xyxCKYb3g_dbxU2w8nX3zDz_X3XqLL8Uha-rkapKbnNgxq4GjM-EBMCill2Svluf9crDmO-SmJbxqIaWzLmlUufQMWg_r8JG7RLseK6ntUDRyDgkF4ex515l2RWqQx7cw874raKgUO4qlx0cpBAB8cRtGHC-3fA7rZPM7UQQpm-BC3suXqRgROTzrKqfn_g-qTW4jAKBIXYG7iDefV2rGMRgem06YH_bDnpkgUa1UgJRRTckkBuLkO2FvA"}

Header Otorisasi diformat sebagai berikut: Bearer <Azure_AD_token>

Respons berisi token MR dalam teks biasa.

Token MR tersebut kemudian dikembalikan ke klien. Aplikasi klien Anda kemudian dapat mengaturnya sebagai token aksesnya dalam konfigurasi sesi cloud:

C#

this.cloudSession.Configuration.AccessToken = @"MyAccessToken";

Objective-C

_cloudSession.configuration.accessToken = @"MyAccessToken";

Swift

_cloudSession!.configuration.accessToken = "MyAccessToken"

Java

mCloudSession.getConfiguration().setAccessToken("MyAccessToken");

C++ NDK

auto configuration = cloudSession_->Configuration();
configuration->AccessToken(R"(MyAccessToken)");

C++/WinRT

auto configuration = m_cloudSession.Configuration();
configuration.AccessToken(LR"(MyAccessToken)");

Kontrol akses berbasis peran Azure

Untuk membantu Anda mengontrol tingkat akses yang diberikan kepada aplikasi, layanan, atau pengguna Microsoft Entra layanan Anda, Anda dapat menetapkan peran yang sudah ada sebelumnya ini sesuai kebutuhan terhadap akun Azure Spatial Anchors Anda:

• Pemilik Akun Spatial Anchors. Aplikasi atau pengguna yang memiliki peran ini dapat membuat spatial anchors, mengkueri spatial anchors, dan menghapus spatial anchors. Saat Anda mengautentikasi ke akun Anda dengan menggunakan kunci akun, peran Pemilik Akun Spatial Anchors ditetapkan ke prinsipal yang diautentikasi.
• Kontributor Akun Spatial Anchors. Aplikasi atau pengguna yang memiliki peran ini dapat membuat spatial anchors dan mengkueri untuk aplikasi atau pengguna, tetapi aplikasi atau pengguna tidak dapat menghapusnya.
• Pembaca Akun Spatial Anchors. Aplikasi atau pengguna yang memiliki peran ini hanya dapat mengkueri spatial anchors. Aplikasi atau pengguna tidak dapat membuat yang baru, menghapus yang sudah ada, atau memperbarui metadata pada spatial anchors. Peran ini biasanya digunakan untuk aplikasi di mana beberapa pengguna mengumpulkan lingkungan tetapi yang lain hanya dapat mengenal jangkar yang sebelumnya ditempatkan di lingkungan.

Langkah berikutnya

Buat aplikasi pertama Anda dengan Spatial Anchors Azure:

Unity (HoloLens)

Unity (iOS)

Unity (Android)

iOS

Android

HoloLens

Xamarin (Android)

Xamarin (iOS)