New-EntraAgentUserForAgentId

Module:
Microsoft.Entra.Users Module v1.3

Hiermee maakt u een nieuwe agentgebruiker met behulp van een agent-id.

Syntax

Default (Standaard) 

New-EntraAgentUserForAgentId

    -DisplayName <String>
    [-UserPrincipalName <String>]
    [-MailNickname <String>]
    [-AgentIdentityId <String>]
    [<CommonParameters>]

Description

De New-EntraAgentUserForAgentId cmdlet maakt een nieuwe agentgebruiker door te posten op het eindpunt van de Microsoft Graph gebruikers met behulp van een agent-id als de bovenliggende identiteit. De mailNickname is standaard afgeleid van het voorvoegsel UserPrincipalName, maar kan worden overschreven met de -MailNickname parameter of interactief. Als -UserPrincipalName dit niet is opgegeven, zoekt de cmdlet het standaarddomein van de tenant op en vraagt deze interactief met een voorgestelde UPN.

Voorbeelden

Voorbeeld 1: Een agentgebruiker maken met alle parameters

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"

In dit voorbeeld wordt een agentgebruiker met de opgegeven weergavenaam en user principal name gemaakt met behulp van de agentidentiteit die in de huidige sessie is gemaakt.

Voorbeeld 2: Een agentgebruiker maken met prompts

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"

In dit voorbeeld wordt een agentgebruiker gemaakt. De cmdlet vraagt om de principal-naam van de gebruiker als deze niet is opgegeven.

Voorbeeld 3: Meerdere agentgebruikers maken voor dezelfde agent-id

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"

In dit voorbeeld worden meerdere agentgebruikers gemaakt die zijn gekoppeld aan dezelfde agentidentiteit.

Voorbeeld 4: Een agentgebruiker maken met expliciete agent-id

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

In dit voorbeeld wordt een agentgebruiker gemaakt door expliciet de id van de agent op te geven. Dit is handig wanneer u aanroept vanuit verschillende modulebereiken of scripts.

Parameters

-AgentIdentityId

De id van de agent die moet worden gekoppeld aan deze gebruiker. Als deze niet is opgegeven, gebruikt de cmdlet de opgeslagen waarde van New-EntraAgentIDForAgentIdentityBlueprint. Gebruik deze parameter bij het aanroepen vanuit verschillende modulebereiken of wanneer u expliciet de agentidentiteit wilt opgeven.

Parametereigenschappen

Type:System.String
Default value:None
Ondersteunt jokertekens:False
DontShow:False

Parametersets

(All)
Position:Named
Verplicht:False
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten:False

-DisplayName

De weergavenaam voor de agentgebruiker.

Parametereigenschappen

Type:System.String
Default value:None
Ondersteunt jokertekens:False
DontShow:False

Parametersets

(All)
Position:Named
Verplicht:True
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten:False

-MailNickname

De bijnaam (alias) van de e-mail voor de agentgebruiker. Als dit niet is opgegeven, wordt het afgeleid van het voorvoegsel UserPrincipalName (het deel vóór het @-symbool) en wordt de gebruiker gevraagd het te bevestigen of te negeren.

Parametereigenschappen

Type:System.String
Default value:None
Ondersteunt jokertekens:False
DontShow:False

Parametersets

(All)
Position:Named
Verplicht:False
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten:False

-UserPrincipalName

De user principal name (email) voor de agentgebruiker (bijvoorbeeld username@domain.onmicrosoft.com). Moet een geldige e-mailadresnotatie zijn. Als dit niet is opgegeven, zoekt de cmdlet het standaarddomein van de tenant op en vraagt deze interactief met een voorgestelde UPN die is afgeleid van de weergavenaam.

Parametereigenschappen

Type:System.String
Default value:None
Ondersteunt jokertekens:False
DontShow:False

Parametersets

(All)
Position:Named
Verplicht:False
Waarde uit pijplijn:False
Waarde uit pijplijn op eigenschapsnaam:False
Waarde van resterende argumenten:False

CommonParameters

Deze cmdlet ondersteunt de algemene parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction en -WarningVariable. Zie about_CommonParametersvoor meer informatie.

Invoerwaarden

None

Uitvoerwaarden

System.Object

Retourneert het agentgebruikersobject van het Microsoft Graph API-antwoord met de volgende eigenschappen:

  • @odata.type — microsoft.graph.agentUser
  • id : de unieke id van de gemaakte agentgebruiker.
  • displayName : de weergavenaam van de agentgebruiker.
  • userPrincipalName : de user principal name van de agentgebruiker.
  • mailNickname : de bijnaam van de e-mail (alias) van de agentgebruiker.
  • accountEnabled : of het account is ingeschakeld (altijd true).
  • identityParentId : de id van de bovenliggende agentidentiteit.

Aanvullende eigenschappen van het Graph API-antwoord kunnen ook worden opgenomen.

Notities

Voor deze cmdlet is de volgende Microsoft Graph-machtiging vereist:

  • AgentIdUser.ReadWrite.All

De id van de agent-id kan worden opgegeven via de -AgentIdentityId parameter of wordt automatisch opgehaald uit de globale variabele $global:EntraCurrentAgentIdentityId die is ingesteld door New-EntraAgentIDForAgentIdentityBlueprint. De globale variabele wordt gebruikt omdat deze cmdlet zich in een andere module (Microsoft.Entra.Users) bevindt dan de blauwdruk-cmdlets (Microsoft.Entra.Applications).

De cmdlet slaat de gemaakte agentgebruikers-id op $script:CurrentAgentUserId voor gebruik door volgende cmdlets.

De cmdlet bevat logica voor opnieuw proberen (maximaal 10 pogingen met 10 seconden wachttijden) voor het afhandelen van doorgiftevertragingen.

Wanneer -UserPrincipalName dit niet is opgegeven, gebruikt u de cmdlet:

  • Query's uitvoeren op het standaarddomein van de tenant via de organisatie-API
  • Stelt een UPN voor door de weergavenaamwoorden samen te voegen als voorvoegsel met het tenantdomein
  • Valideert de UPN op basis van een regex-patroon en vraagt opnieuw als deze ongeldig is

De -UserPrincipalName parameter valideert invoer op basis van het patroon ^[#a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.