Share via

REST üzerinden Azure Dosyalar OAuth ile Microsoft Entra Id kullanarak Azure dosya paylaşımlarını kullanma

  • Makale

REST üzerinden OAuth Azure Dosyalar, kullanıcılar ve uygulamalar için Azure dosya paylaşımlarına yönetici düzeyinde okuma ve yazma erişimi sağlarREST API tabanlı erişim için Microsoft Entra Id kullanarak OAuth kimlik doğrulama protokolü. Kullanıcılar, gruplar, Azure portalı gibi birinci taraf hizmetler ve REST arabirimleri kullanan üçüncü taraf hizmetler ve uygulamalar artık Azure dosya paylaşımlarındaki verilere erişmek için bir Microsoft Entra hesabıyla OAuth kimlik doğrulaması ve yetkilendirme kullanabilir. REST API'lerini çağıran PowerShell cmdlet'leri ve Azure CLI komutları, Azure dosya paylaşımlarına erişmek için OAuth'u da kullanabilir. Ek ayrıcalığı kullanma amacınızı belirtmek için REST API'yi açık bir üst bilgi kullanarak çağırmanız gerekir. Bu, Azure PowerShell ve Azure CLI erişimi için de geçerlidir.

Önemli

Bu makalede, belirli müşteri kullanım örnekleri için Azure dosya paylaşımlarına yönetici düzeyinde erişimin nasıl etkinleştirileceği açıklanmaktadır. Son kullanıcılar için kimlik tabanlı kimlik doğrulaması hakkında daha genel bir makale arıyorsanız bkz. SMB erişimi için Azure Dosyalar kimlik tabanlı kimlik doğrulama seçeneklerine genel bakış.

Sınırlamalar

REST üzerinden OAuth Azure Dosyalar yalnızca dosya ve dizinler üzerindeki işlemleri destekleyen FileREST Veri API'lerini destekler. OAuth, FileService ve FileShare kaynaklarını yöneten FilesREST veri düzlemi API'lerinde desteklenmez. Bu yönetim API'leri Depolama Hesap Anahtarı veya SAS belirteci kullanılarak çağrılır ve eski nedenlerle veri düzlemi aracılığıyla kullanıma sunulur. FileService ve FileShare kaynaklarıyla ilgili tüm yönetim etkinlikleri için OAuth'u destekleyen denetim düzlemi API'lerini (depolama kaynak sağlayıcısı - Microsoft.Depolama) kullanmanızı öneririz.

Microsoft Entra ID ile dosya verileri işlemlerini yetkilendirme yalnızca REST API 2022-11-02 ve sonraki sürümleri için desteklenir. Bkz. Azure Depolama için sürüm oluşturma.

Müşteri kullanım örnekleri

REST API arabirimi üzerinden Azure Dosyalar ile OAuth kimlik doğrulaması ve yetkilendirmesi aşağıdaki senaryolarda müşterilere yararlı olabilir.

Uygulama geliştirme ve hizmet tümleştirmesi

OAuth kimlik doğrulaması ve yetkilendirmesi, geliştiricilerin Microsoft Entra Id'den kullanıcı veya uygulama kimliklerini kullanarak Azure Depolama REST API'lerine erişen uygulamalar oluşturmasına olanak tanır.

Müşteriler ve iş ortakları, bir müşteri depolama hesabına güvenli ve şeffaf bir şekilde gerekli erişimi yapılandırmak için birinci taraf ve üçüncü taraf hizmetleri de etkinleştirebilir.

Azure portalı, PowerShell ve CLI, AzCopy ve Depolama Explorer gibi DevOps araçları kullanıcının kimliğini kullanarak verileri yönetebilir ve depolama erişim anahtarlarını yönetme veya dağıtma gereksinimini ortadan kaldırır.

Yönetilen kimlikler

Yedekleme, geri yükleme veya denetim amacıyla dosya paylaşımı verilerine erişim gerektiren uygulamaları ve yönetilen kimlikleri olan müşteriler OAuth kimlik doğrulaması ve yetkilendirmesinden yararlanabilir. Her kimlik için dosya ve dizin düzeyinde izinlerin zorunlu olması karmaşıklığı artırır ve belirli iş yükleriyle uyumlu olmayabilir. Örneğin müşteriler, dosyaya özgü izinler dikkate alınmadan tüm dosyalara salt okunur erişimle Azure dosya paylaşımlarına erişmek için bir yedekleme çözümü hizmeti yetkilendirmek isteyebilir.

hesap anahtarı değişimini Depolama

Microsoft Entra ID, paylaşılan anahtar erişimi üzerinden üstün güvenlik ve kullanım kolaylığı sağlar. Depolama hesabı anahtarı erişimini OAuth kimlik doğrulaması ve yetkilendirme ile değiştirerek tümünü okuma/tümünü yazma ayrıcalıklarıyla Azure Dosya paylaşımlarına erişebilirsiniz. Bu yaklaşım ayrıca belirli kullanıcı erişimini daha iyi denetleme ve izleme olanağı sunar.

Veri işlemleri için ayrıcalıklı erişim ve erişim izinleri

REST üzerinden Azure Dosyalar OAuth özelliğini kullanmak için kullanıcıya, gruba veya hizmet sorumlusuna atanan RBAC rolüne eklenmesi gereken ek izinler vardır. Bu özelliğin bir parçası olarak iki yeni veri eylemi kullanıma sunulmuştur:

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

OAuth ile REST API'yi çağıran kullanıcıların, grupların veya hizmet sorumlularının veri erişimine izin veren role veya writeFileBackupSemantics eylemi atanmış olması gerekirreadFileBackupSemantics. Bu, bu özelliği kullanmak için bir gereksinimdir. Belirli Dosya hizmeti işlemlerini çağırmak için gereken izinler hakkında ayrıntılı bilgi için bkz . Veri işlemlerini çağırma izinleri.

Bu özellik, bu yeni eylemleri içeren iki yeni yerleşik rol sağlar.

Rol Veri eylemleri
Depolama Dosya Verileri Ayrıcalıklı Okuyucusu Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read
Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action
Depolama Dosya Verileri Ayrıcalıklı Katkıda Bulunanı Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read
Microsoft.Storage/storageAccounts/fileServices/fileShares/files/write
Microsoft.Storage/storageAccounts/fileServices/fileShares/files/delete
Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action
Microsoft.Storage/storageAccounts/fileServices/fileshares/files/modifypermissions/action

Bu yeni roller, mevcut Depolama Dosya Verileri SMB Paylaşım Okuyucusu ve Depolama Dosya Verileri SMB Paylaşımı Yükseltilmiş Katkıda Bulunan yerleşik rollerine benzer, ancak bazı farklılıklar vardır:

  • Yeni roller, OAuth erişimi için gereken ek veri eylemlerini içerir.

  • Dosya Verileri Privileged Reader veya Depolama Dosya Verileri Ayrıcalıklı Katkıda Bulunan rolleri Depolama atanan kullanıcı, grup veya hizmet sorumlusu OAuth kullanarak FilesREST Veri API'sini çağırdığında, kullanıcı, grup veya hizmet sorumlusu şunları içerir:

    • Dosya Verileri Ayrıcalıklı Okuyucusu'Depolama: Ayarlanan dosya/dizin düzeyi NTFS izinlerinden bağımsız olarak, tüm yapılandırılmış depolama hesapları için paylaşımlardaki tüm verilere tam okuma erişimi.
    • dosya verileri ayrıcalıklı katkıda bulunan Depolama: Ayarlanan dosya/dizin düzeyi NTFS izinlerinden bağımsız olarak, tüm yapılandırılmış depolama hesapları için paylaşımlardaki tüm verilere tam okuma, yazma, değiştirme, erişim silme.

  • Bu özel izinler ve rollerle, sistem tüm dosya/dizin düzeyi izinlerini atlar ve dosya paylaşımı verilerine erişime izin verir.

Yeni roller ve veri eylemleriyle bu özellik, depolama hesabındaki tüm dosya paylaşımları altındaki dosya ve klasörlerdeki tüm izinlerin yerini alan depolama hesabı genelinde ayrıcalıklar sağlar. Ancak, yeni roller yalnızca veri hizmetlerine erişim izinleri içerir. Bunlar, dosya paylaşımı yönetim hizmetlerine (dosya paylaşımları üzerindeki eylemler) erişme izni içermez. Bu özelliği kullanmak için erişim izinlerinizin olduğundan emin olun:

  • depolama hesabı
  • dosya paylaşımı yönetim hizmetleri
  • veri hizmetleri (dosya paylaşımındaki veriler)

Yönetim hizmetlerine erişim sağlayan birçok yerleşik rol vardır. Ayrıca uygun izinlere sahip özel roller de oluşturabilirsiniz. Rol tabanlı erişim denetimi hakkında daha fazla bilgi edinmek için bkz . Azure RBAC. Yerleşik rollerin nasıl tanımlandığı hakkında daha fazla bilgi için bkz . Rol tanımlarını anlama.

Önemli

Yol Microsoft.Storage/storageAccounts/fileServices/* veya daha üst kapsam için tanımlanan joker karakter kullanım örnekleri, bu yeni veri eylemi aracılığıyla verilen ek erişimi ve izinleri otomatik olarak devralır. Azure Dosyalar istenmeyen veya fazla ayrıcalıklı erişimi önlemek için, kullanıcıların ve uygulamaların ek ayrıcalığı kullanma amaçlarını açıkça belirtmesini gerektiren ek denetimler uyguladık. Ayrıca, müşterilerin kullanıcı RBAC rol atamalarını gözden geçirmelerini ve uygun veri erişim yönetimi sağlamak için joker karakter kullanımını açık izinlerle değiştirmelerini kesinlikle öneririz.

Uygulama kodundaki dosya verilerine erişimi yetkilendirme

Azure Identity istemci kitaplığı, Azure SDK aracılığıyla Microsoft Entra Id ile yetkilendirme için OAuth 2.0 erişim belirteci alma işlemini basitleştirir. .NET, Java, Python, JavaScript ve Go için Azure Depolama istemci kitaplıklarının en son sürümleri, Azure dosya hizmetinden gelen isteklerin yetkilendirmesi için bir erişim belirteci almak üzere basit ve güvenli bir araç sağlamak üzere bu dillerin her biri için Azure Kimlik kitaplıklarıyla tümleşir.

Azure Identity istemci kitaplığının avantajlarından biri, uygulamanızın geliştirme ortamında veya Azure'da çalıştığına bakılmaksızın erişim belirtecini almak için aynı kodu kullanmanıza olanak tanır. Azure Identity istemci kitaplığı, güvenlik sorumlusu için bir erişim belirteci döndürür. Kodunuz Azure'da çalışırken, güvenlik sorumlusu Azure kaynakları, hizmet sorumlusu veya kullanıcı veya grup için yönetilen bir kimlik olabilir. Geliştirme ortamında, istemci kitaplığı test amacıyla bir kullanıcı veya hizmet sorumlusu için bir erişim belirteci sağlar.

Azure Identity istemci kitaplığı tarafından döndürülen erişim belirteci bir belirteç kimlik bilgisinde kapsüllenmiş. Daha sonra, Azure Dosyalar hizmetine karşı yetkili işlemleri gerçekleştirirken kullanılacak bir hizmet istemci nesnesi almak için belirteç kimlik bilgilerini kullanabilirsiniz.

İşte bazı örnek kodlar:

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

namespace FilesOAuthSample
{
    internal class Program
    {
        static async Task Main(string[] args)
        {
            string tenantId = "";
            string appId = "";
            string appSecret = "";
            string aadEndpoint = "";
            string accountUri = "";
            string connectionString = "";
            string shareName = "test-share";
            string directoryName = "testDirectory";
            string fileName = "testFile"; 

            ShareClient sharedKeyShareClient = new ShareClient(connectionString, shareName); 
            await sharedKeyShareClient.CreateIfNotExistsAsync(); 

            TokenCredential tokenCredential = new ClientSecretCredential(
                tenantId,
                appId,
                appSecret,
                new TokenCredentialOptions()
                {
                    AuthorityHost = new Uri(aadEndpoint)
                });

            ShareClientOptions clientOptions = new ShareClientOptions(ShareClientOptions.ServiceVersion.V2023_05_03);

            // Set Allow Trailing Dot and Source Allow Trailing Dot.
            clientOptions.AllowTrailingDot = true;
            clientOptions.AllowSourceTrailingDot = true;

            // x-ms-file-intent=backup will automatically be applied to all APIs
            // where it is required in derived clients.

            clientOptions.ShareTokenIntent = ShareTokenIntent.Backup;
            ShareServiceClient shareServiceClient = new ShareServiceClient(
                new Uri(accountUri),
                tokenCredential,
                clientOptions);

            ShareClient shareClient = shareServiceClient.GetShareClient(shareName);
            ShareDirectoryClient directoryClient = shareClient.GetDirectoryClient(directoryName);
            await directoryClient.CreateAsync();

            ShareFileClient fileClient = directoryClient.GetFileClient(fileName);
            await fileClient.CreateAsync(maxSize: 1024);
            await fileClient.GetPropertiesAsync();
            await sharedKeyShareClient.DeleteIfExistsAsync();
        }
    }
}

FileREST veri düzlemi API'lerini kullanarak erişimi yetkilendirme

Azure portalını veya Azure PowerShell'i kullanarak dosya verilerine erişim yetkisi de vekleyebilirsiniz.

Azure portalı, Bir Azure depolama hesabındaki dosya verilerine erişmek için Microsoft Entra hesabınızı veya depolama hesabı erişim anahtarınızı kullanabilir. Azure portalının hangi yetkilendirme düzenini kullandığı size atanan Azure rollerine bağlıdır.

Dosya verilerine erişmeye çalıştığınızda, Azure portalı ilk olarak ile Microsoft.Storage/storageAccounts/listkeys/actionbir Azure rolü atanıp atanmadığını denetler. Bu eylemle size bir rol atandıysa, Azure portalı paylaşılan anahtar yetkilendirmesi aracılığıyla dosya verilerine erişmek için hesap anahtarını kullanır. Bu eylemle size bir rol atanmamışsa, Azure portalı Microsoft Entra hesabınızı kullanarak verilere erişmeyi dener.

Microsoft Entra hesabınızı kullanarak Azure portalından dosya verilerine erişmek için dosya verilerine erişim izinlerine ve azure portalındaki depolama hesabı kaynakları arasında gezinmek için izinlere de ihtiyacınız vardır. Azure tarafından sağlanan yerleşik roller dosya kaynaklarına erişim verir, ancak depolama hesabı kaynaklarına izin vermez. Bu nedenle portala erişim için, depolama hesabı düzeyine veya daha yüksek bir düzeye sahip Okuyucu rolü gibi bir Azure Resource Manager (ARM) rolü atamanız da gerekir. Okuyucu rolü en kısıtlayıcı izinleri verir, ancak depolama hesabı yönetim kaynaklarına erişim veren tüm ARM rolleri kabul edilebilir.

Azure portalda bir kapsayıcıya gittiğinizde hangi kimlik doğrulama düzeninin kullanımda olduğu gösterilir. Portalda veri erişimi hakkında daha fazla bilgi için bkz . Azure portalında dosya verilerine erişimi yetkilendirmeyi seçme.

Ayrıca bkz.