Ajouter des permissions "Mail.Send" de la Graph API à une identité managée

Ajouter des permissions "Mail.Send" de la Graph API à une identité managée

Comment utiliser les capacités d'envoi de mail de Microsoft 365 en utilisant les services sécurisés Azure

Qu’est qu’une Identité managée ?

Une identité managée sur Azure (Managed Identity) est un service fourni par Microsoft Azure pour simplifier la gestion des identités dans les applications déployées sur Azure.

Une identité managée permet à vos applications de s'authentifier auprès de services Azure et autres ressources sans avoir à gérer de manière explicite des informations d'identification (comme des noms d'utilisateur et mots de passe ou des clés d'accès).

Voici les deux types d'identités managées :

  1. Identité managée attribuée par le système (System-assigned Managed Identity) :

    • Cette identité est automatiquement créée par Azure pour une ressource spécifique.

    • Elle est liée au cycle de vie de la ressource, ce qui signifie qu'elle est supprimée lorsque la ressource est supprimée.

    • Par exemple, une machine virtuelle, une application web, ou une fonction Azure peut avoir une identité managée attribuée par le système.

      Exemple d’identité managée associée à une web app:

  2. Identité managée attribuée par l'utilisateur (User-assigned Managed Identity) :

    • Cette identité est créée comme une ressource Azure distincte.

    • Elle peut être assignée à une ou plusieurs ressources.

    • Elle continue d'exister indépendamment des ressources auxquelles elle est associée.

      Exemple d’un identité managée attribuée par l’utilisateur:

User Assigned Identity

A quoi sert la Graph API ?

Azure Graph API est une interface de programmation qui permet aux développeurs d'accéder aux services Microsoft Graph, lesquels fournissent une interface unifiée pour interagir avec diverses données et services dans Microsoft 365, Azure Active Directory (Azure AD), et plus encore.

Types de permissions

  1. Delegated permissions (Permissions déléguées) :

    • Utilisées par les applications qui se connectent au nom d'un utilisateur.

    • L'utilisateur doit s'authentifier et consentir aux permissions demandées par l'application.

    • Exemple : Mail.Send permet à l'application d'envoyer des courriels au nom de l'utilisateur authentifié.

  2. Application permissions (Permissions d'application) :

    • Utilisées par les applications qui s'authentifient en tant que propre entité, sans l'intervention d'un utilisateur spécifique.

    • Nécessite une approbation administrative.

    • Exemple : Mail.Send permet à l'application d'envoyer des courriels à partir de toute boîte aux lettres au sein de l'organisation.

Ajouter la permission “Mail.Send”

La permission Mail.Send dans Microsoft Graph API permet aux applications d'envoyer des courriels au nom de l'utilisateur authentifié ou d'une boîte aux lettres.

Pré-requis

Pour ajouter des permissions à une identité managée (Managed Identity) dans Azure, il est important de disposer des droits appropriés pour effectuer les modifications nécessaires tels que Application Administrator, Contributor, ou Managed Identity Contributor sur les ressources concernées.

💡
Assurez-vous que les rôles sont bien attribués pour éviter des erreurs d'autorisation lors de la gestion des identités managées et de leurs permissions.

Détail des commandes utilisées

Via le portail Azure, récupérer l’objectID de votre identité et lancer la console Cloud Shell en mode Azure CLI:

  1. Création de la variable ObjectID:

     objectId=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
    
  2. Récupération des IDs de la Graph API:

     graphResourceId=$(az ad sp list --display-name "Microsoft Graph" --query [0].id --out tsv)
     appRoleId=$(az ad sp list --display-name "Microsoft Graph" --query "[0].appRoles[?value=='Mail.Send' && contains(allowedMemberTypes, 'Application')].id" --output tsv)
    
  3. Appel à l’API pour ajouter les droits :

     uri=https://graph.microsoft.com/v1.0/servicePrincipals/$principalId/appRoleAssignments
     body="{'principalId':'$objectId','resourceId':'$graphResourceId','appRoleId':'$appRoleId'}"
     az rest --method post --uri $uri --body $body --headers "Content-Type=application/json"
    
  4. Résultat attendu de la commande

  5. Validation de l’ajout de la permission via le portail Azure

Script complet en Azure CLI

objectId=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

graphResourceId=$(az ad sp list --display-name "Microsoft Graph" --query [0].id --out tsv)
appRoleId=$(az ad sp list --display-name "Microsoft Graph" --query "[0].appRoles[?value=='Mail.Send' && contains(allowedMemberTypes, 'Application')].id" --output tsv)

uri=https://graph.microsoft.com/v1.0/servicePrincipals/$principalId/appRoleAssignments
body="{'principalId':'$objectId','resourceId':'$graphResourceId','appRoleId':'$appRoleId'}"
az rest --method post --uri $uri --body $body --headers "Content-Type=application/json"

Envoi d'un courriel

Une fois que vous avez configuré la permission à votre identité, vous pouvez envoyer un courriel en utilisant, par exemple, un Runbook Azure Automation.

Voici un script d’exemple simple pour valider le fonctionnement :

# Authenticate using Managed Identity
$resource = "https://graph.microsoft.com"
$clientId = (Invoke-WebRequest -Uri "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$resource" -Headers @{Metadata="true"}).Content | ConvertFrom-Json
$accessToken = $clientId.access_token

# Prepare the email
$emailBody = @{
    Message = @{
        Subject = "Test Email from Azure Automation"
        Body = @{
            ContentType = "Text"
            Content = "This is a test email sent from Azure Automation using Microsoft Graph API."
        }
        ToRecipients = @(
            @{
                EmailAddress = @{
                    Address = "recipient@example.com"
                }
            }
        )
    }
    SaveToSentItems = "true"
}

# Convert the email body to JSON
$emailBodyJson = $emailBody | ConvertTo-Json -Depth 10

# Send the email using Microsoft Graph API
$sendMailUri = "https://graph.microsoft.com/v1.0/me/sendMail"
$response = Invoke-RestMethod -Uri $sendMailUri -Headers @{Authorization = "Bearer $accessToken"; "Content-Type" = "application/json"} -Method POST -Body $emailBodyJson

# Output the response
$response

Conclusion

Ajouter des permissions "Mail.Send" de la Graph API à une identité managée dans Azure permet d'automatiser l'envoi d'e-mails de manière sécurisée et efficace. En utilisant des identités managées, vous pouvez éviter les problèmes de gestion de secrets et d'informations d'identification, tout en bénéficiant des fonctionnalités robustes de Microsoft Graph pour gérer et interagir avec les services Office 365.

Pour récapituler, voici les principales étapes pour configurer cette capacité :

  1. Création d'une identité managée (assignée par le système ou par l'utilisateur) dans Azure.

  2. Attribution des permissions nécessaires, en ajoutant l'API "Mail.Send" à l'identité managée.

  3. Obtention d'un jeton d'accès en utilisant l'identité managée pour authentifier les appels à l'API Microsoft Graph.

  4. Envoi d'e-mails via un script PowerShell ou toute autre méthode de script, en utilisant le jeton d'accès obtenu.

En automatisant ces étapes dans un environnement comme Azure Automation, vous pouvez intégrer de manière fluide l'envoi d'e-mails dans vos workflows, qu'il s'agisse de notifications d'événements, de rapports automatisés, ou de toute autre communication essentielle.

En suivant les bonnes pratiques et les étapes décrites dans cet article, vous pouvez tirer pleinement parti des capacités d'Azure et de Microsoft Graph pour automatiser des tâches critiques, augmentant ainsi l'efficacité et la sécurité de vos opérations cloud.

Did you find this article valuable?

Support Antoine LOIZEAU by becoming a sponsor. Any amount is appreciated!