Microsoft Entra Agent ID
Developer

Control access to agents with app roles

In brief

The article now explains defining inbound roles, assigning them to callers, and enforcing them in the agent API. It distinguishes single-instance and fleet workflows and updates the required principals, permissions, and administrative roles.

What Entra admins need to know

Administrators implementing access control should follow the revised role-definition and assignment locations and review the updated Graph permissions and role requirements.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

Control user access to agents with app roles

This article describes howApp roles define who can access an agent and what they can do. Use them to control userrestrict agent operations to approved users, groups, or client applications.

In this article, you define an inbound access role, assign it to a caller, and enforce it in the agent access to applications using app roles andAPI. Where you define the assignmentRequired property. It covers defining app roles, enforcing explicit role assignments, assigning roles using Microsoft Graphdepends on whether the agent uses a single-instance blueprint or the Microsoft Entra admin center, and best practices for secure access management.a fleet.

Prerequisites

  • An existingA blueprint and its agent identity blueprint already created and configuredAPI service principal.
  • Agent ID Administrator role for managing agent identities and assignments
  • Application Administrator or Cloud Application Administrator role for managing app roles and assignmentRequired properties
  • AppRoleAssignment.ReadWrite.All permission forAn authorized Microsoft Graph API operations if using programmatic approach.

What are app roles?

App roles define logical permissions or access levelsmanagement client for an application. They're declared role configuration. For delegated single-instance management, the signed-in user must own the agent identity or have the Agent ID Administrator role. See Update servicePrincipal for the applicable API permissions.

  • Application Administrator or Cloud Application Administrator to manage user and group app role assignments.
  • AppRoleAssignment.ReadWrite.All and the appropriate read permission for programmatic assignments.
  • For the single-instance cloud journey, the API's service principal is the agent identity, not a blueprint principal. Use its object ID as <agent-api-service-principal-object-id> in the requests in this article. A single-instance blueprint has no blueprint principal. For the advanced fleet journey, use the fleet's blueprint principal instead; its assignments apply across the fleet.

    Define app roles

    Choose the definition location for your instance mode:

    Instance modeDefine the inbound role onAssign the role on
    Single-instanceThe blueprint application and can be assignedthe Agent ID service principal, using the same role GUID and value.The Agent ID service principal.
    FleetThe blueprint application.The blueprint principal that represents the fleet API.

    Use one role when everyone has the same access level. For example, use Agent.User for standard tasks and add Agent.Admin only if you expose administrative tasks. Keep role values stable because your authorization policies check them.

    Declare the role on the blueprint

    Define Agent.User in the blueprint application's appRoles collection. For a single-instance agent, also complete the next section to users, groups, service principals, or agent identities.make the same role available on its Agent ID.

    Read the blueprint's existing appRoles first. The following section showsrequest is for a blueprint with no existing roles. For an example appexisting collection, include the existing role definition:definitions you intend to retain; updating appRoles replaces the collection. Omit the read-only origin field from requests.

    Replace <agent-user-role-id> with a new GUID and save it for the assignment step:

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    Content-Type: application/json
    Authorization: Bearer <management-access-token>
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "appRoles": [
        {
          "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890<agent-user-role-id>",
          "allowedMemberTypes": ["User", "Application"],
          "description": "Grants ability to invokeUse standard agent actionsfeatures",
          "displayName": "AgentInvokerAgent user",
          "isEnabled": true,
          "value": "AgentInvokerAgent.User"
        }
      ]
    }
    
    • Single-instance user access

      For a single-instance agent, publish the same user role directly in the Agent ID's appRoles collection. Use the same GUID and value as the blueprint declaration, not a second role GUID. The blueprint-only declaration doesn't make the role available for assignment on the Agent ID. The service-principal-only definition doesn't complete the blueprint configuration used in this procedure.

      Read the Agent ID's existing roles first and retain their definitions in the update. For an Agent ID with no existing roles, send:

      PATCH https://graph.microsoft.com/beta/servicePrincipals/<agent-api-service-principal-object-id>
      Content-Type: application/json
      Authorization: Bearer <management-access-token>
      
      {
        "appRoles": [
          {
            "id": "<agent-user-role-id>",
            "allowedMemberTypes": ["User"],
            "description": "Use standard agent features",
            "displayName": "Agent user",
            "isEnabled": true,
            "value": "Agent.User"
          }
        ]
      }
      

      This is role configuration on two separate objects, not permission inheritance or a downstream API grant. Don't create a blueprint principal for a single-instance agent.

      The service-principal definition supports User for users and groups. Don't add Application to this request: roles assignable to client applications must be defined on an application object. This single-instance procedure covers inbound user access, not application-only callers. See the appRole resource reference.

      Fleet access

      For a fleet, use the blueprint declaration without the single-instance service-principal update. Include User in allowedMemberTypes controls who can be assigned (users, apps,for users or both)groups and Application for client applications. For the application-level procedure, see Add app roles to an application.

    • Use the blueprint principal, not a child Agent ID, as the resource for inbound assignments.

      Verify the role on the resource principal

      Before requiring or assigning a role, read back the blueprint with GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=appRoles and the agent API principal with GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-api-service-principal-object-id>?$select=appRoles. Use an authorized management client, not the agent's runtime token.

      Confirm that the principal's appRoles contains the role's exact id and value, that isEnabled is true, and that allowedMemberTypes includes the string that appears in the token's roles claim when assigned.

    intended assignee type.

    If an agent identityassignment returns Permission being assigned was not found on application, check the role definition on the resource principal and the assignment's resourceId and appRoleId. For a single-instance agent, complete the direct definition above if you defined the role only on the blueprint. Don't create a blueprint principal, substitute another resource, or remove the API's role check. Continue only after the intended principal exposes no app-roles, the default app-role <guid of all zeros> can be used to assign principals to the agent identity.

    When designing app roles for your agent applications, define granular roles that separate duties and responsibilities. For example, create specific roles like "AgentInvoker" for users who can call agent actions and "AgentAdmin" for users who can manage agent configurations. This approach provides better security control and makes it easier to audit access patterns.role.

    What is assignmentRequired?

    The assignmentRequired property on an application or agent identity determines whether role assignment is mandatory for access.

    • assignmentRequired = true → Only principals explicitly assignedRequire an app role can sign in or callassignment

      Set appRoleAssignmentRequired on the agent identity.

    • API service principal. When the property is assignmentRequired = falsetrue → Any authenticated principal can, Microsoft Entra ID issues an access token for the agent identity (subjectAPI only to other conditions).

    Why use assignmentRequired?

    You might use the assignmentRequired property for the following reasons:

    • Enforces least privilege by requiring explicit assignment.
    • Prevents accidental access byassigned users or agents who weren't intended to use the agent.

    Enable assignmentRequired for sensitive agent identity blueprints to enforce explicit role assignment and ensure only authorized principals can access critical agent functionality. If users can access an application without explicit assignment, it indicates that assignmentRequired is set to false. Change this setting to true and assign roles explicitly to maintain security controls.

    Configure assignmentRequired

    The following example uses the Update application API to set the assignmentRequired property.applications.

    PATCH https://graph.microsoft.com/v1.0/applications/servicePrincipals/<agent-app-api-service-principal-object-id>
    Content-Type: application/json
    Authorization: Bearer <access-token>
    
    {
      "appRoleAssignmentRequired": true
    }
    

    The assignmentRequired property ensures that only principals explicitly assignedFor more information, see the Microsoft Graph update API reference.

    Assign an app role can access the agent identity blueprint, enforcing least privilege and preventing accidental access.

    Assign app roles to control access

    App roles are granted through app role assignments. They link a principal (user, group, or agent identity) to a specific app role onAssign the target agent identity. If an agent identity fails to access an application after configuration, verify that an appRoleAssignment is created for the agent identity using the APIs shown in the following example.

    Assign an app role to a user

    The following example uses on the Grant an appRoleAssignment to a useragent API to assign an app role to a user.service principal:

    POST https://graph.microsoft.com/v1.0/users/<user-object-id>/appRoleAssignments
    Content-Type: application/json
    Authorization: Bearer <access-token with AppRoleAssignment.ReadWrite.All>
    Content-Type: application/json
    
    {
      "principalId": "<user-object-id>",
      "resourceId": "<agent-identity-blueprint-api-service-principal-object-id>",
      "appRoleId": "<app-role-id>"
    }
    

    Assign an

    Use the GUID saved when you defined Agent.User as <app-role-id>. For a group, create the assignment through the group's app role toassignments. For a fleet role that allows Application, create a client application's assignment through that client's service principal. In every case, use the agent API service principal's object ID as resourceId.

    Enforce app roles in the agent API

    When an assigned user or application gets an access token for the agent identity

    API, Microsoft Entra ID includes the assigned app role values in the token's roles claim. The following example usesagent API checks that claim before it allows the Grantrequested operation.

    After configuring authentication and token validation, add an authorization policy that requires the app role:

    In appRoleAssignmentProgram.cs, merge the policy registration into builder.Services.AddAuthorization tobefore builder.Build(). Place the endpoint mapping after the authentication and authorization middleware and before app.Run(); the two parts of this fragment aren't adjacent in a complete application.

    builder.Services.AddAuthorization(options =>
    {
        options.AddPolicy(
            "AgentUser",
            policy => policy.RequireRole("Agent.User"));
    });
    
    app.MapPost("/tasks", () => Results.Accepted())
        .RequireAuthorization("AgentUser");
    

    AddAuthorization registers the ASP.NET Core authorization services. RequireRole checks the authenticated identity for the Agent.User role. Microsoft.Identity.Web recognizes Microsoft Entra app roles in the access token's roles claim.

    Call UseAuthentication before UseAuthorization in the middleware pipeline, as shown in the authentication article. Request a new access token after changing an assignment. When troubleshooting, verify the assignment on the agent API service principal API to assign an app role to an agent identity.and the token's roles claim.

    POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
    Authorization: Bearer <

    With a new token with AppRoleAssignment.ReadWrite.All> Content-Type: application/json { "principalId": "<agent-identity-id>", "resourceId": "<agent-identity-blueprint-principal-id>", "appRoleId": "<app-role-id>" }

    Verify role assignment

    To verify your role assignment, be sure to take the following actions:

    • List appRoleAssignments for the user or agent identity.
    • CheckAPI and the roles claim inassigned Agent.User role, the sample POST /tasks returns 202 Accepted. Without a token, expect 401; an otherwise valid token after sign-in.

    If roles claims are missing from tokens, verifywithout that role is rejected with 403 if the tenant issues it. When assignment exists with the correct appRoleId, then request a new token. Regularly audit these assignments using Microsoft Graph or theis required, Microsoft Entra admin center to ensure they remain appropriate and remove any unnecessary access.ID might reject sign-in or token issuance before the request reaches your API.

    Related content

    Daily Entra.News

    Get daily email updates

    Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

    Loading the secure signup form…