Edit

Govern membership and ownership of groups using PIM for groups

  • Article

With Privileged Identity Management for groups (PIM for groups), you can govern how principals are assigned membership or ownership of groups. Security and Microsoft 365 groups are critical resources that you can use to provide access to Microsoft cloud resources like Microsoft Entra roles, Azure roles, Azure SQL, Azure Key Vault, Intune; and third-party applications. PIM for groups gives you more control over how and when principals are members or owners of groups, and therefore have privileges granted through their group membership or ownership.

The PIM for groups APIs in Microsoft Graph provide you with more governance over security and Microsoft 365 groups such as the following capabilities:

  • Providing principals just-in-time membership or ownership of groups
  • Assigning principals temporary membership or ownership of groups

This article introduces the governance capabilities of the APIs for PIM for groups in Microsoft Graph.

PIM for groups APIs for managing active assignments of group owners and members

The PIM for groups APIs in Microsoft Graph allow you to assign principals permanent or temporary and time-bound membership or ownership to groups.

The following table lists scenarios for using PIM for groups APIs to manage active assignments for principals and the corresponding APIs to call.

Scenarios API
An administrator:
  • Assigns a principal active membership or ownership to a group
  • Renews, updates, extends, or removes a principal from their active membership or ownership to a group

    A principal:
  • Performs just-in-time and time-bound activation of their eligible membership or ownership assignment for a group
  • Deactivates their eligible membership and ownership assignment it when they no longer need access
  • Deactivates, extends, or renews their own membership and ownership assignment
    		•  Create assignmentScheduleRequest
    An administrator lists all requests for active membership and ownership assignments for a group List assignmentScheduleRequests
    An administrator lists all active assignments, and requests for assignments to be created in the future, for membership and ownership for a group List assignmentSchedules
    An administrator lists all active membership and ownership assignments for a group List assignmentScheduleInstances
    An administrator queries a member and ownership assignment for a group and its details Get privilegedAccessGroupAssignmentScheduleRequest
    A principal queries their membership or ownership assignment requests and the details

    An approver queries membership or ownership requests waiting for their approval and details of these requests    		 privilegedAccessGroupAssignmentScheduleRequest: filterByCurrentUser
    A principal cancels a membership or ownership assignment request they created privilegedAccessGroupAssignmentScheduleRequest: cancel
    An approver gets details for approval request, including information about approval steps Get approval
    An approver approves or denies approval request by approving or denying approval step Update approvalStep

    PIM for groups APIs for managing eligible assignments of group owners and members

    Your principals may not require permanent membership or ownership of groups because they may not require the privileges granted through the membership or ownership all the time. In this case, PIM for groups allows you to make the principals eligible for the membership or ownership of the groups.

    When a principal has an eligible assignment, they activate their assignment when they need the privileges granted through the groups to perform privileged tasks. An eligible assignment can be permanent or temporary. The activation is always time-bound for up to a maximum of eight hours.

    The following table lists scenarios for using PIM for groups APIs to manage eligible assignments for principals and the corresponding APIs to call.

    Scenarios API
    An administrator:
  • Creates an eligible membership or ownership assignment for the group
  • Renews, updates, extends, or removes an eligible membership/ownership assignment for the group
  • Deactivates, extends, or renews their own membership/ownership eligibility
    		•  Create eligibilityScheduleRequest
    An administrator queries all eligible membership or ownership requests and their details List eligibilityScheduleRequests
    An administrator queries an eligible membership or ownership request and its details Get eligibilityScheduleRequest
    An administrator cancels an eligible membership or ownership request they created privilegedAccessGroupEligibilityScheduleRequest:cancel
    A principal queries their eligible membership or ownership request their details privilegedAccessGroupEligibilityScheduleRequest: filterByCurrentUser

    Policy settings in PIM for groups

    PIM for groups defines settings or rules that govern how principals can be assigned membership or ownership of security and Microsoft 365 groups. Such rules include whether multifactor authentication (MFA), justification, or approval is required to activate an eligible membership or ownership for a group, or whether you can create permanent assignments or eligibilities for principals to the groups. The rules are defined in policies and a policy can be applied to a group.

    In Microsoft Graph, these rules are managed through the unifiedRoleManagementPolicy and the unifiedRoleManagementPolicyAssignment resource types and their related methods.

    For example, assume that by default, PIM for groups doesn't allow permanent active membership and ownership assignments and defines a maximum of six months for active assignments. Attempting to create a privilegedAccessGroupAssignmentScheduleRequest object without expiry date returns a 400 Bad Request response code for violation of the expiration rule.

    PIM for groups allows you to configure various rules including:

    • Whether principals can be assigned permanent eligible assignments
    • The maximum duration allowed for a group membership or ownership activation and whether justification or approval is required to activate eligible membership or ownership
    • The users who are allowed to approve activation requests for a group membership or ownership
    • Whether MFA is required to both activate and enforce a group membership or ownership assignment
    • The principals who get notified of group membership or ownership activations

    The following table lists scenarios for using PIM for groups to manage rules and the APIs to call.

    Scenarios API
    Retrieve PIM for groups policies and associated rules or settings List unifiedRoleManagementPolicies
    Retrieve a PIM for groups policy and its associated rules or settings Get unifiedRoleManagementPolicy
    Update a PIM for groups policy on its associated rules or settings Update unifiedRoleManagementPolicy
    Retrieve the rules defined for a PIM for groups policy List rules
    Retrieve a rule defined for a PIM for groups policy Get unifiedRoleManagementPolicyRule
    Update a rule defined for a PIM for groups policy Update unifiedRoleManagementPolicyRule
    Get the details of all PIM for groups policy assignments, including the policies and rules associated with the groups membership and ownership List unifiedRoleManagementPolicyAssignments
    Get the details of a PIM for groups policy assignment, including the policy and rules associated with the groups membership or ownership Get unifiedRoleManagementPolicyAssignment

    For more information about using Microsoft Graph to configure rules, see Overview of rules in PIM APIs in Microsoft Graph. For examples of updating rules, see Use PIM APIs in Microsoft Graph to update rules.

    Onboarding groups to PIM for groups

    You can't onboard a group to PIM for groups explicitly. When you request to add assignment to group using Create assignmentScheduleRequest or Create eligibilityScheduleRequest, or you update PIM policy (role settings) for a group using Update unifiedRoleManagementPolicy or Update unifiedRoleManagementPolicyRule, the group is onboarded to PIM automatically if it wasn't onboarded before.

    You can call List assignmentScheduleRequests, List assignmentSchedules, List assignmentScheduleInstances, List eligibilityScheduleRequests, List eligibilitySchedules, and List eligibilityScheduleInstances APIs for both groups that are onboarded to PIM and groups that aren't onboarded to PIM yet, but we recommend doing it only for groups that are onboarded to PIM to reduce the chances of getting throttled

    After PIM onboards a group, IDs of the PIM policies and policy assignments of the specific group change. Call the Get unifiedRoleManagementPolicy or Get unifiedRoleManagementPolicyAssignment API to get the updated IDs.

    Once PIM onboards a group, you can't offboard it, but you can remove all eligible and time-bound assignments as necessary.

    PIM for groups and the group object

    Membership and ownership of any security and Microsoft 365 group (except dynamic groups and groups synchronized from on-premises) can be governed through PIM for groups. The group doesn't have to be role-assignable to be enabled in PIM for groups.

    When you assign a principal active permanent or temporary membership or ownership of a group, or when they make a just-in-time activation:

    When a principal is assigned eligible permanent or temporary membership or ownership of a group, the members and owners relationships of the group aren't updated.

    When a principal's temporary active membership or ownership of a group expires:

    • The principal's details are automatically removed from the members and owners relationships.
    • If changes to the group are tracked using the Get delta and Get delta for directory objects functions, an @odata.nextLink indicates the removed group member or owner.

    Zero Trust

    This feature helps organizations to align their identities with the three guiding principles of a Zero Trust architecture:

    • Verify explicitly
    • Use least privilege
    • Assume breach

    To find out more about Zero Trust and other ways to align your organization to the guiding principles, see the Zero Trust Guidance Center.

    Permissions and privileges

    The following Microsoft Graph permissions are required to call the PIM for groups APIs.

    Endpoints Supported operations Permissions
    assignmentSchedule
    assignmentScheduleInstance    		 LIST, GET PrivilegedAssignmentSchedule.Read.AzureADGroup
    PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup
    assignmentScheduleRequest CREATE, LIST, GET, UPDATE, DELELE PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup
    eligibilitySchedule
    eligibilityScheduleInstance    		 LIST, GET PrivilegedEligibilitySchedule.Read.AzureADGroup
    PrivilegedEligibilitySchedule.ReadWrite.AzureADGroup
    eligibilityScheduleRequest CREATE, LIST, GET, UPDATE, DELELE PrivilegedEligibilitySchedule.ReadWrite.AzureADGroup
    approval GET PrivilegedAssignmentSchedule.Read.AzureADGroup
    PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup
    approvalStep LIST, GET PrivilegedAssignmentSchedule.Read.AzureADGroup
    PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup
    approvalStep UPDATE PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup
    roleManagementPolicy
    roleManagementPolicyAssignment    		 LIST, GET RoleManagementPolicy.Read.AzureADGroup
    RoleManagementPolicy.ReadWrite.AzureADGroup
    roleManagementPolicy UPDATE RoleManagementPolicy.ReadWrite.AzureADGroup

    In addition, for delegated scenarios, the calling principal needs one of the following roles (not applicable to approval and approvalStep endpoints).

    Group Role Supported operations
    Role-assignable Privileged Role Administrator
    Group owner*
    Group member*    		 CREATE, UPDATE, DELELE
    Role-assignable Global Reader
    Privileged Role Administrator
    Group owner*
    Group member*    		 LIST, GET
    Non-role-assignable Directory Writer
    Groups Administrator
    Identity Governance Administrator
    User Administrator
    Group owner*
    Group member*    		 CREATE, UPDATE, DELELE
    Non-role-assignable Global Reader
    Directory Writer
    Groups Administrator
    Identity Governance Administrator
    User Administrator
    Group owner*
    Group member*    		 LIST, GET

    * Permissions for group members and group owners are limited to the read or write operations they need to perform. For example, a group member can cancel their assignmentScheduleRequest but not any other principal's request.

    Only the approver of the request can call the /approval and /approvalStep endpoints. They don't have to be assigned any Microsoft Entra roles.

    Related content