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 tentang cara menggunakan kontrol akses berbasis peran Azure (RBAC Azure) di Azure Active Directory (Azure AD) untuk mengontrol akses ke akun Spatial Anchors.

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 Azure Active Directory berbasis pengguna atau layanan yang dijelaskan berikutnya.

Gambaran Umum

Diagram that shows an overview of authentication to Azure Spatial Anchors.

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 sebagai ganti kunci akun atau token yang dikeluarkan oleh Azure Active Directory.

Kunci akun memungkinkan Anda memulai dengan cepat menggunakan layanan Spatial Anchors Azure. Namun sebelum menyebarkan aplikasi ke produksi, kami menyarankan Anda memperbarui aplikasi untuk menggunakan autentikasi Azure Active Directory.

Anda dapat memperoleh token autentikasi Azure Active Directory dengan dua cara:

  • Jika sedang membangun aplikasi perusahaan dan perusahaan menggunakan Azure Active Directory sebagai sistem identitasnya, Anda dapat menggunakan autentikasi Azure Active Directory berbasis pengguna di aplikasi. Anda kemudian memberikan akses ke akun Spatial Anchors dengan menggunakan kelompok keamanan Azure Active Directory yang sudah ada. Anda juga dapat memberikan akses langsung ke pengguna di organisasi Anda.
  • Jika tidak, kami menyarankan Anda mendapatkan token Azure Active Directory dari layanan web yang mendukung aplikasi. 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:

Screenshot that shows the Keys tab with the Copy button for the Primary key highlighted.

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:

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

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

Autentikasi pengguna Azure Active Directory

Untuk aplikasi yang menargetkan pengguna Azure Active Directory, kami menyarankan Anda menggunakan token Azure Active Directory untuk pengguna. Anda dapat memperoleh token ini dengan menggunakan MSAL. Ikuti langkah-langkah dalam mulai cepat untuk mendaftarkan aplikasi, yang meliputi:

Di portal Azure

  1. Daftarkan aplikasi Anda di Azure Active Directory 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 memiliki peran yang berbeda terhadap akun ASA, daftarkan beberapa aplikasi di Azure AD 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 Azure Active Directory Anda sendiri untuk parameter ID klien dan RedirectUri di MSAL.
  2. Mengatur 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 Azure Active Directory bahwa aplikasi Anda meminta token untuk Layanan Token Keamanan (STS) Azure Mixed Reality.

Setelah Anda menyelesaikan langkah-langkah ini, aplikasi Anda seharusnya dapat memperoleh token Azure Active Directory dari MSAL. Anda dapat mengatur token Azure Active Directory tersebut sebagai authenticationToken pada objek konfigurasi sesi cloud:

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

Autentikasi layanan Azure Active Directory

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

Diagram that provides an overview of authentication to Azure Spatial Anchors.

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 Azure Active Directory, menukarnya dengan token akses untuk Azure Spatial Anchors, dan mengembalikannya kembali ke aplikasi klien Anda.

Token akses Azure Active Directory diambil melalui MSAL. Ikuti langkah-langkah di Mendaftarkan mulai cepat aplikasi, yang meliputi:

Di portal Azure

  1. Mendaftarkan aplikasi Anda di Azure Active Directory:
    1. Di portal Azure, pilih Azure Active Directory, 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 memiliki peran yang berbeda terhadap akun ASA, daftarkan beberapa aplikasi di Azure AD 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 mengalihkan URI aplikasi Azure Active Directory Anda sendiri sebagai parameter ID klien, rahasia, dan RedirectUri di MSAL.
  2. Atur ID penyewa ke ID penyewa Azure Active Directory Anda sendiri di parameter otoritas di MSAL.
  3. Pada permintaan token Anda, atur cakupan ke https://sts.mixedreality.azure.com//.default .

Setelah menyelesaikan langkah-langkah ini, layanan ujung belakang Anda dapat mengambil token Azure Active Directory. Layanan ujung belakang kemudian dapat menukarnya dengan token MR yang akan dikembalikan ke klien. Menggunakan token Azure Active Directory 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:

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

Kontrol akses berbasis peran Azure

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

  • 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:

iOS