New-EntraAgentUserForAgentId
Crée un utilisateur agent à l’aide d’une identité d’agent.
Syntaxe
Default (Par défaut)
New-EntraAgentUserForAgentId
-DisplayName <String>
[-UserPrincipalName <String>]
[-MailNickname <String>]
[-AgentIdentityId <String>]
[<CommonParameters>]
Description
L’applet New-EntraAgentUserForAgentId de commande crée un utilisateur agent en publiant sur le point de terminaison Microsoft Graph utilisateurs à l’aide d’un ID d’identité de l’agent en tant que parent d’identité d’identité. Le nom mailNickname est dérivé du préfixe UserPrincipalName par défaut, mais peut être remplacé par le -MailNickname paramètre ou de manière interactive. S’il -UserPrincipalName n’est pas fourni, l’applet de commande recherche le domaine par défaut du locataire et invite de manière interactive avec un UPN suggéré.
Exemples
Exemple 1 : Créer un utilisateur agent avec tous les paramètres
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "My Blueprint" -SponsorUserIds @("admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity" -SponsorUserIds @("user1@contoso.com")
New-EntraAgentUserForAgentId -DisplayName "Agent Identity 26192008" -UserPrincipalName "AgentIdentity26192008@contoso.onmicrosoft.com"
Cet exemple crée un utilisateur agent avec le nom d’affichage et le nom d’utilisateur principal spécifiés, à l’aide de l’identité de l’agent créée dans la session active.
Exemple 2 : Créer un utilisateur agent avec des invites
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
# Assumes Agent Identity Blueprint and Agent Identity are already created
New-EntraAgentUserForAgentId -DisplayName "HR Agent User"
Cet exemple crée un utilisateur agent. L’applet de commande demande le nom d’utilisateur principal s’il n’est pas fourni.
Exemple 3 : Créer plusieurs utilisateurs d’agent pour la même identité d’agent
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
New-EntraAgentIdentityBlueprint -DisplayName "Finance Blueprint" -SponsorUserIds @("finance-admin@contoso.com")
New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "Finance Agent" -SponsorUserIds @("finance-user@contoso.com")
# Create first Agent User
New-EntraAgentUserForAgentId -DisplayName "Finance Agent User 1" -UserPrincipalName "financeagent1@contoso.onmicrosoft.com"
# Create second Agent User for the same Agent Identity
New-EntraAgentUserForAgentId -DisplayName "Finance Agent User 2" -UserPrincipalName "financeagent2@contoso.onmicrosoft.com"
Cet exemple crée plusieurs utilisateurs de l’agent associés à la même identité d’agent.
Exemple 4 : Créer un utilisateur agent avec un ID d’identité d’agent explicite
Connect-Entra -Scopes 'AgentIdentityBlueprint.Create', 'AgentIdentityBlueprintPrincipal.Create', 'AgentIdentity.Create.All', 'AgentIdentityBlueprint.UpdateAuthProperties.All', 'AgentIdUser.ReadWrite.All'
$agentIdentity = New-EntraAgentIDForAgentIdentityBlueprint -DisplayName "My Agent Identity"
New-EntraAgentUserForAgentId -DisplayName "Agent User" -UserPrincipalName "agentuser@contoso.onmicrosoft.com" -AgentIdentityId $agentIdentity.id
Cet exemple crée un utilisateur agent en fournissant explicitement l’ID d’identité de l’agent, ce qui est utile lors de l’appel à partir de différentes étendues de module ou de scripts.
Paramètres
-AgentIdentityId
ID d’identité de l’agent à associer à cet utilisateur. Si elle n’est pas fournie, l’applet de commande utilise la valeur stockée de New-EntraAgentIDForAgentIdentityBlueprint. Utilisez ce paramètre lors de l’appel à partir de différentes étendues de module ou lorsque vous souhaitez spécifier explicitement l’identité de l’agent.
Propriétés du paramètre
| Type: | System.String |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-DisplayName
Nom complet de l’utilisateur agent.
Propriétés du paramètre
| Type: | System.String |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | True |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-MailNickname
Surnom de messagerie (alias) de l’utilisateur agent. S’il n’est pas fourni, il est dérivé du préfixe UserPrincipalName (la partie avant le symbole @) et l’utilisateur est invité à confirmer ou à le remplacer.
Propriétés du paramètre
| Type: | System.String |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
-UserPrincipalName
Nom d’utilisateur principal (e-mail) de l’utilisateur agent (par exemple). username@domain.onmicrosoft.com Doit être un format d’adresse e-mail valide. Si elle n’est pas fournie, l’applet de commande recherche le domaine par défaut du locataire et invite de manière interactive un UPN suggéré dérivé du nom d’affichage.
Propriétés du paramètre
| Type: | System.String |
| Valeur par défaut: | None |
| Prend en charge les caractères génériques: | False |
| DontShow: | False |
Jeux de paramètres
(All)
| Position: | Named |
| Obligatoire: | False |
| Valeur du pipeline: | False |
| Valeur du pipeline par nom de propriété: | False |
| Valeur des arguments restants: | False |
CommonParameters
Cette applet de commande prend en charge les paramètres courants : -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction et -WarningVariable. Pour plus d’informations, consultez about_CommonParameters.
Entrées
None
Sorties
System.Object
Retourne l’objet Utilisateur de l’agent à partir de la réponse Microsoft API Graph avec les propriétés suivantes :
-
@odata.type —
microsoft.graph.agentUser - ID : identificateur unique de l’utilisateur de l’agent créé.
- displayName : nom d’affichage de l’utilisateur de l’agent.
- userPrincipalName : nom d’utilisateur principal de l’utilisateur agent.
- mailNickname : surnom de messagerie (alias) de l’utilisateur de l’agent.
-
accountEnabled : indique si le compte est activé (toujours
true). - identityParentId : ID de l’identité de l’agent parent.
Des propriétés supplémentaires de la réponse API Graph peuvent également être incluses.
Notes
Cette applet de commande nécessite l’autorisation Microsoft Graph suivante :
AgentIdUser.ReadWrite.All
L’ID d’identité de l’agent peut être fourni via le -AgentIdentityId paramètre ou est automatiquement récupéré à partir de la variable $global:EntraCurrentAgentIdentityId globale définie par New-EntraAgentIDForAgentIdentityBlueprint. La variable globale est utilisée, car cette applet de commande se trouve dans un autre module (Microsoft.Entra.Users) que les applets de commande blueprint (Microsoft.Entra.Applications).
L’applet de commande stocke l’ID utilisateur de l’agent créé pour $script:CurrentAgentUserId une utilisation par les applets de commande suivantes.
L’applet de commande inclut une logique de nouvelle tentative (jusqu’à 10 tentatives avec 10 secondes d’attente) pour gérer les retards de propagation.
Quand -UserPrincipalName elle n’est pas fournie, l’applet de commande :
- Interroge le domaine par défaut du locataire via l’API de l’organisation
- Suggère un UPN en concaténant les mots de nom d’affichage en tant que préfixe avec le domaine de locataire
- Valide l’UPN par rapport à un modèle regex et invite à nouveau s’il n’est pas valide
Le -UserPrincipalName paramètre valide l’entrée par rapport au modèle ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.