appRoleAssignment resource type

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Used to record when a user, group, or service principal is assigned an app role for an app.

An app role assignment is a relationship between the assigned principal (a user, a group, or a service principal), a resource application (the app's service principal) and an app role defined on the resource application.

When the app role which has been assigned to a principal has a non-empty value property, this will be included in the roles claim of tokens where the subject is the assigned principal (e.g. SAML responses, ID tokens, access tokens identifying a signed-in user, or an access token identifying a service principal). Applications and APIs use these claims as part of their authorization logic.

A user can be assigned an app role directly. If an app role is assigned to a group, direct members of the group are also considered to have been assigned the app role. When a user is assigned an app role for an application, a tile for that application is displayed in the user's MyApps portal and Microsoft 365 app launcher.

An app role assignment where the assigned principal is a service principal is an app-only permission grant. When a user or admin consents to an app-only permission, an app role assignment is created where the assigned principal is the service principal for the client application, and the resource is the target API's service principal.

Methods

Method Return type Description
List appRoleAssignments granted to a group appRoleAssignment collection Get a list of the appRoleAssignment objects and their properties.
List appRoleAssignments granted to a user appRoleAssignment collection Get a list of the appRoleAssignment objects and their properties.
List appRoleAssignments granted to a service principal appRoleAssignment collection Get a list of the appRoleAssignment objects and their properties.
List appRoleAssignments granted to users, groups, and client service principals for a resource service principal appRoleAssignment collection Get a list of the appRoleAssignment objects and their properties.
Grant an appRole to a group appRoleAssignment Create a new appRoleAssignment object.
Grant an appRole to a user appRoleAssignment Create a new appRoleAssignment object.
Grant an appRole to a service principal appRoleAssignment collection Create a new appRoleAssignment object.
Grant a user, group, or client service principal an appRoleAssignment for a resource service principal appRoleAssignment collection Create a new appRoleAssignment object.
Get appRoleAssignment appRoleAssignment Get a new appRoleAssignment object.
Dlete an appRoleAssignment from a group None Delete an appRoleAssignment object.
Delete an appRoleAssignment from a user None Delete an appRoleAssignment object.
Delete an appRoleAssignment from a service principal None Delete an appRoleAssignment object.
Delete an appRoleAssignment granted to a user, group, or client service principal for a resource service principal None Delete an appRoleAssignment object.

Properties

Property Type Description
id String A unique identifier for the appRoleAssignment key. Not nullable. Read-only.
creationTimestamp DateTimeOffset The time when the app role assignment was created. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. Read-only.
principalId Guid The unique identifier (id) for the user, security group, or service principal being granted the app role. Security groups with dynamic memberships are supported. Required on create.
principalType String The type of the assigned principal. This can either be User, Group, or ServicePrincipal. Read-only.
principalDisplayName String The display name of the user, group, or service principal that was granted the app role assignment. Read-only. Supports $filter (eq and startswith).
resourceId Guid The unique identifier (id) for the resource service principal for which the assignment is made. Required on create. Supports $filter (eq only).
resourceDisplayName String The display name of the resource app's service principal to which the assignment is made.
appRoleId Guid The identifier (id) for the app role which is assigned to the principal. This app role must be exposed in the appRoles property on the resource application's service principal (resourceId). If the resource application has not declared any app roles, a default app role ID of 00000000-0000-0000-0000-000000000000 can be specified to signal that the principal is assigned to the resource app without any specific app roles. Required on create.

JSON representation

Here is a JSON representation of the resource

{
  "id": "String",
  "creationTimestamp": "String (timestamp)",
  "principalDisplayName": "String",
  "principalId": "Guid",
  "principalType": "String",
  "resourceDisplayName": "String",
  "resourceId": "Guid",
  "appRoleId": "Guid"
}