Accéder aux partages de fichiers Azure à l’aide de Microsoft Entra ID avec Azure Files OAuth sur REST

2025-05-07

Azure Files OAuth sur REST permet l’accès en lecture et en écriture au niveau de l’administrateur aux partages de fichiers Azure pour les utilisateurs et les applications via le protocole d’authentification OAuth , à l’aide de l’ID Microsoft Entra pour l’accès basé sur l’API REST. Les utilisateurs, les groupes, les services internes tels que le portail Azure et les services et applications tiers utilisant des interfaces REST peuvent désormais utiliser l’authentification et l’autorisation OAuth avec un compte Microsoft Entra pour accéder aux données dans des partages de fichiers Azure. Les applets de commande PowerShell et les commandes Azure CLI qui appellent des API REST peuvent également utiliser OAuth pour accéder aux partages de fichiers Azure. Vous devez appeler l’API REST à l’aide d’un en-tête explicite pour indiquer votre intention d’utiliser le privilège supplémentaire. Cela est également vrai pour l’accès Azure PowerShell et Azure CLI.

Important

Cet article explique comment activer l’accès au niveau de l’administrateur aux partages de fichiers Azure pour des cas d’usage clients spécifiques. Si vous recherchez un article plus général sur l’authentification basée sur l’identité pour les utilisateurs finaux, consultez Vue d’ensemble de l’authentification basée sur l’identité Azure Files pour l’accès SMB.

S’applique à

Modèle de gestion	Modèle de facturation	Échelon médiatique	Redondance
Microsoft.Storage	V2 approvisionné	HDD (standard)	Local (LRS)
Microsoft.Storage	V2 approvisionné	HDD (standard)	Zone (ZRS)
Microsoft.Storage	V2 approvisionné	HDD (standard)	Géo (GRS)
Microsoft.Storage	V2 approvisionné	HDD (standard)	GeoZone (GZRS)
Microsoft.Storage	V1 approvisionné	SSD (Premium)	Local (LRS)
Microsoft.Storage	V1 approvisionné	SSD (Premium)	Zone (ZRS)
Microsoft.Storage	Paiement à l’utilisation	HDD (standard)	Local (LRS)
Microsoft.Storage	Paiement à l’utilisation	HDD (standard)	Zone (ZRS)
Microsoft.Storage	Paiement à l’utilisation	HDD (standard)	Géo (GRS)
Microsoft.Storage	Paiement à l’utilisation	HDD (standard)	GeoZone (GZRS)

Limites

L’autorisation des opérations de données de fichier avec l’ID Microsoft Entra est prise en charge uniquement pour les versions 2022-11-02 et ultérieures de l’API REST.

La prise en charge d’Azure Files OAuth sur REST pour les API de plan de données REST Azure Files qui gèrent les ressources FileService et FileShare est disponible avec les versions 2024-11-04 et ultérieures de l’API REST.

Consultez Contrôle de version pour stockage Azure.

Cas d’usage du client

L’authentification et l’autorisation OAuth avec Azure Files sur l’interface de l’API REST peuvent bénéficier aux clients dans les scénarios suivants.

Développement d'applications et intégration des services

L’authentification et l’autorisation OAuth permettent aux développeurs de créer des applications qui accèdent aux API REST stockage Azure à l’aide d’identités utilisateur ou d’application à partir de l’ID Microsoft Entra.

Les clients et les partenaires peuvent également permettre aux services tiers et internes de configurer l’accès nécessaire de manière sécurisée et transparente à un compte de stockage client.

Les outils DevOps tels que le portail Azure, PowerShell et l’interface CLI, AzCopy et l’Explorateur Stockage peuvent gérer les données à l’aide de l’identité de l’utilisateur, ce qui élimine la nécessité de gérer ou de distribuer des clés d’accès de stockage.

Identités managées

Les clients disposant d’applications et d’identités managées qui nécessitent l’accès aux données de partage de fichiers à des fins de sauvegarde, de restauration ou d’audit peuvent bénéficier de l’authentification et de l’autorisation OAuth. L’application des autorisations au niveau du fichier et du répertoire pour chaque identité ajoute de la complexité et peut ne pas être compatible avec certaines charges de travail. Par exemple, les clients peuvent souhaiter autoriser un service de solution de sauvegarde à accéder aux partages de fichiers Azure avec un accès en lecture seule à tous les fichiers sans tenir compte des autorisations spécifiques aux fichiers.

Remplacement de la clé de compte de stockage

Microsoft Entra ID offre une sécurité et une facilité d’utilisation supérieures sur l’accès à clé partagée. Vous pouvez remplacer l'accès à la clé du compte de stockage par l'authentification et l'autorisation OAuth pour accéder aux partages de fichiers Azure avec des privilèges de lecture complète/écriture complète. Cette approche offre également un meilleur audit et un suivi de l’accès utilisateur spécifique.

Accès privilégié et autorisations d’accès pour les opérations de données

Pour utiliser la fonctionnalité OAuth Azure Files sur REST, il existe des autorisations supplémentaires requises pour être incluses dans le rôle RBAC attribué à l’utilisateur, au groupe ou au principal du service. Deux nouvelles actions de données sont introduites dans le cadre de cette fonctionnalité :

Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action

Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action

Les utilisateurs, les groupes ou les principaux de service qui appellent l'API REST avec OAuth doivent avoir soit l’action readFileBackupSemantics, soit l’action writeFileBackupSemantics assignée au rôle qui autorise l’accès aux données. Il s’agit d’une exigence d’utilisation de cette fonctionnalité. Pour plus d’informations sur les autorisations requises pour appeler des opérations de service de fichiers spécifiques, consultez Autorisations pour appeler des opérations de données.

Cette fonctionnalité fournit deux nouveaux rôles intégrés qui incluent ces nouvelles actions.

Rôle	Actions de données
Lecteur privilégié des données du fichier de stockage	`Microsoft.Storage/storageAccounts/fileServices/fileShares/files/read` `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`
Contributeur privilégié des données du fichier de stockage	`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`

Ces nouveaux rôles sont similaires aux rôles intégrés existants Lecteur de partage SMB des données du fichier de stockage et Contributeur avec privilèges élevés de partage SMB des données du fichier de stockage, mais il existe quelques différences :

Les nouveaux rôles contiennent les actions de données supplémentaires requises pour l’accès OAuth.
Lorsque l’utilisateur, le groupe ou le principal de service assigné aux rôles Lecteur privilégié des données de fichier de stockage ou Contributeur privilégié des données de fichier de stockage appelle l’API de données FilesREST à l’aide d’OAuth, l’utilisateur, le groupe ou le principal de service aura :
- Lecteur privilégié des données de fichier de stockage : Accès en lecture complet sur toutes les données des partages pour tous les comptes de stockage configurés, quelles que soient les autorisations NTFS au niveau du fichier/répertoire définies.
- Contributeur privilégié des données du fichier de stockage : Accès en lecture, écriture, modification des ACL et suppression complète sur toutes les données des partages pour tous les comptes de stockage configurés, quelles que soient les autorisations NTFS définies au niveau du fichier/répertoire.
Avec ces autorisations et rôles spéciaux, le système contourne les autorisations au niveau du fichier/répertoire et autorise l’accès aux données de partage de fichiers.

Avec les nouveaux rôles et actions de données, cette fonctionnalité fournit des privilèges à l’échelle du compte de stockage qui remplacent toutes les autorisations sur les fichiers et dossiers sous tous les partages de fichiers dans le compte de stockage. Toutefois, les nouveaux rôles contiennent uniquement des autorisations pour accéder aux services de données. Ils n’incluent aucune autorisation d’accès aux services de gestion des partages de fichiers (actions sur les partages de fichiers). Pour utiliser cette fonctionnalité, vérifiez que vous disposez des autorisations d’accès :

le compte de stockage
services de gestion de partage de fichiers
services de données (données dans le partage de fichiers)

Il existe de nombreux rôles intégrés qui fournissent l’accès aux services de gestion. Vous pouvez également créer des rôles personnalisés avec les autorisations appropriées. Pour en savoir plus sur le contrôle d’accès en fonction du rôle, consultez Azure RBAC. Pour plus d’informations sur la définition des rôles intégrés, consultez Comprendre les définitions de rôles.

Gardez à l’esprit que pour le type de ressource de partage de fichiers, l’étendue RBAC correspondante utilise shares dans le plan de contrôle (opérations de gestion), mais utilise fileshares dans le plan de données (opérations de données). Si vous essayez d’utiliser un ID de ressource de partage de fichiers qui contient shares dans l’étendue RBAC ou les chaînes d’action de données, cela ne fonctionnera pas. Vous devez utiliser fileshares dans l’étendue des affectations RBAC, par exemple :

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>/fileServices/default/fileshares/<share-name>

Important

Tous les cas d’usage génériques définis pour le chemin d’accès Microsoft.Storage/storageAccounts/fileServices/* ou l’étendue supérieure héritent automatiquement de l’accès et des autorisations supplémentaires accordés avec cette nouvelle action de données. Pour éviter un accès involontaire ou sur-privilégié à Azure Files, nous avons implémenté des vérifications supplémentaires qui exigent que les utilisateurs et les applications indiquent explicitement leur intention d’utiliser les privilèges supplémentaires. En outre, nous recommandons vivement aux clients de passer en revue leurs attributions de rôles RBAC utilisateur et de remplacer toute utilisation générique par des autorisations explicites pour garantir une gestion appropriée de l’accès aux données.

Autoriser l’accès aux données de fichier dans le code de l’application

La bibliothèque de client Azure Identity simplifie le processus d’obtention d’un jeton d’accès OAuth 2.0 pour l’autorisation avec Microsoft Entra ID via le Kit de développement logiciel (SDK) Azure. Les dernières versions des bibliothèques clientes stockage Azure pour .NET, Java, Python, JavaScript et Go s’intègrent aux bibliothèques d’identité Azure pour chacun de ces langages afin de fournir un moyen simple et sécurisé d’acquérir un jeton d’accès pour l’autorisation des demandes du service de fichiers Azure.

L’avantage de la bibliothèque de client Azure Identity est qu’elle vous permet d’utiliser le même code pour acquérir le jeton d’accès, que votre application s’exécute dans l’environnement de développement ou dans Azure. La bibliothèque cliente Azure Identity retourne un jeton d’accès pour un principal de sécurité. Lorsque votre code s’exécute dans Azure, le principal de sécurité peut être une identité managée pour les ressources Azure, un principal de service ou un utilisateur ou un groupe. Dans l’environnement de développement, la bibliothèque cliente fournit un jeton d’accès pour un utilisateur ou un principal de service à des fins de test.

Le jeton d’accès retourné par la bibliothèque cliente Azure Identity est encapsulé dans des informations d’identification de jeton. Vous pouvez ensuite utiliser les informations d’identification du jeton pour obtenir un objet client de service à utiliser pour effectuer des opérations autorisées sur le service Azure Files.

L’exemple de code suivant montre comment autoriser un objet client à l’aide de Microsoft Entra ID et effectuer des opérations au niveau du répertoire et du fichier. Cet exemple part du principe que le partage de fichiers existe déjà.

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 entraEndpoint = "";
            string accountUri = "https://<storage-account-name>.file.core.windows.net/";
            string shareName = "test-share";
            string directoryName = "test-directory";
            string fileName = "test-file";  

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

            // Set client options
            ShareClientOptions clientOptions = new ShareClientOptions();
            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();
        }
    }
}

Autoriser l’accès à l’aide de l’API de plan de données FileREST

Vous pouvez également autoriser l’accès aux données de fichiers à l’aide du portail Azure, d’Azure PowerShell ou d’Azure CLI.

Le portail Azure peut utiliser votre compte Microsoft Entra ou la clé d’accès du compte de stockage pour accéder aux données de fichier dans un compte de stockage Azure. Le schéma d’autorisation utilisé par le portail Azure dépend des rôles Azure qui vous sont attribués.

Lorsque vous tentez d’accéder aux données de fichier, le portail Azure vérifie d’abord si vous avez reçu un rôle Azure avec Microsoft.Storage/storageAccounts/listkeys/action. Si vous avez reçu un rôle avec cette action, le portail Azure utilise la clé de compte pour accéder aux données de fichier via l’autorisation de clé partagée. Si vous n’avez pas été affecté à un rôle avec cette action, le portail Azure tente d’accéder aux données à l’aide de votre compte Microsoft Entra.

Pour accéder aux données de fichier à partir du portail Azure à l’aide de votre compte Microsoft Entra, vous avez besoin d’autorisations pour accéder aux données de fichier, et vous avez également besoin d’autorisations pour parcourir les ressources du compte de stockage dans le portail Azure. Les rôles intégrés fournis par Azure accordent l’accès aux ressources de fichiers, mais ils n’accordent pas d’autorisations aux ressources du compte de stockage. Pour cette raison, l’accès au portail nécessite également l’attribution d’un rôle Azure Resource Manager (ARM), tel que le rôle Lecteur , limité au niveau du compte de stockage ou supérieur. Le rôle Lecteur accorde les autorisations les plus restrictives, mais tout rôle ARM qui accorde l’accès aux ressources de gestion des comptes de stockage est acceptable.

Le portail Azure indique le schéma d’autorisation utilisé lorsque vous accédez à un conteneur. Pour plus d’informations sur l’accès aux données dans le portail, consultez Choisir comment autoriser l’accès aux données de fichiers dans le portail Azure.

Azure fournit des extensions pour PowerShell qui vous permettent de vous connecter et d’appeler des applets de commande PowerShell à l’aide des informations d’identification Microsoft Entra. Lorsque vous vous connectez à PowerShell avec les informations d’identification Microsoft Entra, un jeton d’accès OAuth 2.0 est retourné. PowerShell utilise automatiquement ce jeton pour autoriser les opérations de données suivantes sur le stockage de fichiers. Pour les opérations prises en charge, vous n’avez plus besoin de fournir une clé de compte ou le jeton SAP avec la commande.

Vous pouvez attribuer des autorisations aux données de fichier à un principal de sécurité Microsoft Entra via Azure RBAC.

Opérations prises en charge

Les extensions prennent uniquement en charge les opérations sur les données de fichier. Les opérations que vous pouvez appeler dépendent des autorisations accordées au principal de sécurité Microsoft Entra avec lequel vous vous êtes connecté à PowerShell.

Le contexte de stockage avec OAuth fonctionne uniquement s’il est appelé avec le -EnableFileBackupRequestIntent paramètre. Il s’agit de spécifier l’intention explicite d’utiliser les autorisations supplémentaires que cette fonctionnalité fournit.

Le contexte de stockage avec OAuth fonctionne uniquement pour les opérations sur les fichiers et les répertoires, et obtenir/définir des autorisations sur des partages de fichiers Azure. Pour toutes les autres opérations sur le compte de stockage et les partages de fichiers, vous devez utiliser la clé de compte de stockage ou le jeton SAP.

Conditions préalables

Vous aurez besoin d’un groupe de ressources Azure et d’un compte de stockage au sein de ce groupe de ressources. Le compte de stockage doit être affecté à un rôle approprié qui accorde des autorisations explicites pour effectuer des opérations de données sur des partages de fichiers. Vérifiez que vous disposez des rôles et des autorisations nécessaires pour accéder aux services de gestion et aux services de données. Pour plus d’informations sur les autorisations requises pour appeler des opérations de service de fichiers spécifiques, consultez Autorisations pour appeler des opérations de données.

Installer le module Az.Storage

Cette fonctionnalité est disponible dans le dernier module Az.Storage. Installez le module à l’aide de cette commande :

Install-Module Az.Storage -Repository PsGallery

Autoriser l’accès aux données de fichier

Pour autoriser l’accès aux données de fichier, procédez comme suit.

Connectez-vous à votre compte Azure à l'aide du cmdlet Connect-AzAccount.
Obtenez le contexte du compte de stockage à l’aide de la clé de compte de stockage en appelant l’applet Get-AzStorageAccount de commande (service de gestion). Remplacez <ResourceGroupName> et <StorageAccountName> par vos valeurs.
```
$ctxkey = (Get-AzStorageAccount -ResourceGroupName <ResourceGroupName> -Name <StorageAccountName>).Context
```
Créez un partage de fichiers en appelant New-AzStorageShare. Étant donné que vous utilisez le contexte du compte de stockage à partir de l’étape 2, le partage de fichiers est créé à l’aide de votre clé de compte de stockage.
```
$fileshareName = "sample-share"
New-AzStorageShare -Name $fileshareName -Context $ctxkey
```
Obtenez le contexte du compte de stockage à l’aide d’OAuth pour effectuer des opérations de données sur le partage de fichiers (service de données). Remplacez <StorageAccountName> par le nom de votre compte de stockage.
```
$ctx = New-AzStorageContext -StorageAccountName <StorageAccountName> -EnableFileBackupRequestIntent
```
Pour obtenir le contexte du compte de stockage avec OAuth, vous devez transmettre explicitement le -EnableFileBackupRequestIntent paramètre à l’applet New-AzStorageContext de commande. Si vous ne transmettez pas le paramètre d’intention, les demandes d’opération de données de partage de fichiers suivantes à l’aide du contexte échouent.
Créez un répertoire de test et un fichier dans le partage de fichiers à l’aide des applets de commande New-AzStorageDirectory et Set-AzStorageFileContent. N’oubliez pas de spécifier un chemin d’accès de fichier source local.
```
$dir = New-AzStorageDirectory -ShareName $fileshareName -Path "dir1" -Context $ctx
$file = Set-AzStorageFileContent -ShareName $fileshareName -Path "test2" -Source "<local source file path>" -Context $ctx  
```
Étant donné que les applets de commande sont appelées à l’aide du contexte du compte de stockage à l’étape 4, le fichier et le répertoire sont créés à l’aide des informations d’identification Microsoft Entra.

Les commandes Azure CLI principales fournies dans le cadre de l’interface CLI prennent en charge les fichiers OAuth via l’interface REST, et vous pouvez les utiliser pour authentifier et autoriser les opérations de données de fichier à l’aide des informations d’identification Microsoft Entra.

Opérations prises en charge

Les commandes prennent uniquement en charge les opérations sur les données de fichier. Les opérations que vous pouvez appeler dépendent des autorisations accordées au principal de sécurité Microsoft Entra avec lequel vous vous êtes connecté à Azure CLI.

L'authentification et l'autorisation OAuth fonctionneront uniquement si la commande CLI est appelée avec l'option --backup-intent ou l'option --enable-file-backup-request-intent. Il s’agit de spécifier l’intention explicite d’utiliser les autorisations supplémentaires que cette fonctionnalité fournit.

Toutes les commandes des groupes az storage file, az storage directory, az storage share list-handle et az storage share close-handle prennent en charge l'authentification et l'autorisation OAuth. Pour toutes les autres opérations sur le compte de stockage et les partages de fichiers, vous devez utiliser la clé de compte de stockage ou le jeton SAP.

Conditions préalables

Installation et exemples de commandes

Si ce n’est déjà fait, installez la dernière version d’Azure CLI.