Transitioning from GUM APIs

> To Entra ID APIs

M365 Graph API permissions:

If your application requires the following Graph APIs (see below table), these Graph APIs are classified as Low Risk. Note that APIs and M365 approval window takes 5-10 business days.

Permission	CISO Approval	ARR	Archer Exception
Group.Create	N	Y	N
User.Read.All	N	Y	N
GroupMember.Read.All	N	Y	N

Today, PwC Identity's Group and User Management 2.0 (GUM 2.0) Application Programme Interfaces (APIs) provide a mechanism for applications to programmatically create and manage external users and groups in the PwC Identity service (ForgeRock OpenIDM and OpenDJ).

As PwC Identity transitions from ForgeRock products to Entra ID as its global Identity solution, applications leveraging current Group & User Management (GUM) APIs will need to update their applications to leverage Entra ID APIs to programmatically:

• Create external/guest users in Entra ID
• Manage Entra ID Groups
• Carry out various other identity management operations according to their application's requirements

A decision was made to deprecate the GUM 2.0 solution in favor of having applications integrated directly with Entra ID APIs. This was mainly for three reasons:

1. GUM is custom built solution on top of ForgeRock OpenIDM. As PwC transitions to Entra ID, having a custom-built solution in front of a SaaS service adds complexity and cost.

2. GUM uses Simple Object Access Protocol (SOAP). SOAP is an outdated messaging protocol that is no longer used and has since been replaced by REST. If GUM were updated it would include moving to REST, which would still require applications to make changes.

3. Entra ID has a robust set of APIs with 99.999% availability.

This document will assist application owners in transitioning from GUM APIs to Entra ID APIs by mapping GUM API to Entra ID API to perform the same function.

High-Level API Comparison

GUM API function	Available Entra ID APIs	Additional information
Create User	✅ Yes	See Create User
Validate User by Email	✅ Yes	See Validate User by Email
AzureGuestADCheck	✅ Yes	See Validate User by Email
AzureGuestADCreate	✅ Yes	See Create User
Update User	✅ Yes	Limited with Guest Users
Lock Account	✅ Yes	Called Account Disabled/Enabled in Entra ID
Add Delegated Account Owner	✅ Yes	Referred to as a Sponsor in Entra ID
Create Group	✅ Yes	Security Group Only
Update Group	✅ Yes	Security Group Only
Update Group Displayed Owner	❌ No	See Add Group Owner
Add Group Owner	✅ Yes	Security Group Only
Remove Group Owner	✅ Yes	Security Group Only
Add Group Member	✅ Yes	Security Group Only
Remove Group Member	✅ Yes	Security Group Only
Validate User by GUID	❌ No	PwC GUIDs do not exist in Entra ID.Unique Identifiers are UPN/email and ObjectID
Validate Group by GUID	❌ No	Unique Identifiers for groups are ObjectID
Get Application Names	TBD
Reset Password	❌ No	External Guest users do not have passwords.Entra ID uses B2B or bring your own Identity.
Reset Questions	❌ No	Security questions do not exist in Entra ID
Update Assurance Level	❌ No	External Guest users in Entra ID do not have different levels, you are just a guest.
Remove Delegated Account Owner	❌ No	Entra ID does not have concept of account owner
Help User	❌ No	Specific to PwC Identity to send user an account activation email or password reset link.

Requesting Entra ID API access

To access PwC Entra ID tenant via APIs, application owners must submit a request and receive approval before access to Graph APIs is allowed. The M365@PwC SharePoint Site provides guidance for obtaining this approval.

Processing Time

This process can take weeks depending on the type of access needed by an application.

Detailed API Methods

For additional information about all of these methods, Microsoft provides a robust set of articles on their APIs that can be found here.

Create / Invite User

Required API Permissions

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.Invite.All	✅ No	⚠️ Yes	✅ No
User.Read.All	✅ No	⚠️ Yes	✅ No

📖 Reference: MS article with additional details on this method

This method allows applications to create/invite an external user to PwC's Entra ID tenant.

When creating/inviting guest users, there are three required attributes:

1. InvitedUserEmailAddress – the user's email address
2. InvitedUserDisplayName – the user's full name
3. InviteRedirectUrl – the URL to which the user will be redirected once the invitation is redeemed; it is recommended to set to https://myapps.microsoft.com, but can be any valid URL

Sample Code

By default, when creating/inviting a user, no email is sent to the user. If you wish to send standard Entra ID invite email, you can do so by passing sendInvitationMessage:true.

Use the tabs below to toggle between each scenario:

Without Invite Email

Create/Invite user without invite email

POST https://graph.microsoft.com/v1.0/invitations
{
"invitedUserEmailAddress": " User's email address",
"invitedUserDisplayName": "Users name as you want displayed",
"inviteRedirectUrl": "https://myapps.microsoft.com"
}

With Invite Email

Create/invite user AND send invite email

POST https://graph.microsoft.com/v1.0/invitations
{
"invitedUserEmailAddress": " User's email address",
"invitedUserDisplayName": " User's name as you want displayed",
"inviteRedirectUrl": "https://myapps.microsoft.com",
"sendInvitationMessage": true
}

Note the sendInvitationMessage:true parameter

---

Validate / Search User by Email

Required API Permissions

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.Read.All	✅ No	⚠️ Yes	✅ No

📖 Reference: MS article with additional details on this method

This method will allow an application query PwC's Entra ID tenant to see if a guest account already exists.

Sample Code

Search User By Email

GET https://graph.microsoft.com/v1.0/users?$filter=(mail+eq+'USEREMAIL')

By default, a limited set of properties are returned ( businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName)

If you want to return specific attributes you can add &$select=

Search User By Email + Additional Attributes

GET https://graph.microsoft.com/v1.0/users?$filter=(mail+eq+'USEREMAIL')&$select=displayName,mail,userPrincipalName,userType,createdDateTime,externalUserState,id

Null Value Responses

Search user is a standard method to find any user account, guest or member, in your Entra ID tenant. Therefore, the results will include some attributes with null values - such as jobTitle or mobilePhone - because they are not used for, or do not exist in Entra ID for guest accounts.

AzureGuestADCheck

See Validate / Search User by Email Method.

AzureGuestADCreate

See Create / Invite User Method.

---

Update User

Required API Permissions

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.ReadWrite.All	⚠️ Yes - All Territories	⚠️ Yes	⚠️ Yes

Security Checkpoint

This operation requires elevated rights in Entra ID, which is not part of the default permissions granted to invite/create guest users.

📖 Reference: MS article with additional details on this method

PwC's Entra ID tenant allows applications to update a limited number of guest user account attributes via the methods described in this guide. The table below describes each attribute, and the correct operation for updating it:

Guest User Account Attribute	How to update
displayName	Follow the Update User method described directly below this table
givenName	Follow the Update User method described directly below this table
surname	Follow the Update User method described directly below this table
email	Update User Email and Reset Redemption Status method
resetRedemption	Update User Email and Reset Redemption Status method
accountEnabled	Enable / Disable Account method

Sample Code

This method will update a guest user account's displayName, givenName, and/or surname in PwC's Entra ID tenant.

Update guest user display name, given name and surname

PATCH https://graph.microsoft.com/v1.0/users/{id}
{
"displayName": "Sally Smith",
"giveName": "Sally",
"surname": "Smith"
}

---

Update User Email and Reset Redemption Status

Required API Permissions

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.ReadWrite.All	⚠️ Yes - All Territories	⚠️ Yes	⚠️ Yes
User.Invite.All	✅ No	⚠️ Yes	✅ No

📖 Reference: MS article with additional details on this method

There might be times when you'll need to update as users email address/sign-in information, for example when:

• The user changed their email in their home tenant and wants to sign and receive emails to that new address.
• They need to reset their B2B Identity provider
• The account for the user in their home tenant was deleted and re-created, resulting in a new Object ID (oid) for the account that needs to be linked to their guest account in the PwC Tenant.

This method will allow an application to update a guest user account in PwC's Entra ID tenant.

Sample Code

This is a multiple step process. Before you can call the invitations API to update the user's redemption status and their email, you must update the mail attribute with the new email.

Step 1 - Update guest user account email address

PATCH https://graph.microsoft.com/v1.0/users/{id}
{
"mail": "New email address",
}

After setting the user new email to the mail attribute, you can then reset the redemptionStatus with the user's new email.

Step 2 - Reset redemptionStatus

POST
{
"invitedUserEmailAddress": "New email address",
"inviteRedirectUrl": "https://myapps.microsoft.com",
"invitedUser": {
"id": "ObjectID for the user you want to reset"
},
"resetRedemption": true
}

---

Enable / Disable Account

Required API Permissions

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.ReadWrite.All	⚠️ Yes - All Territories	⚠️ Yes	⚠️ Yes
User.Invite.All	✅ No	⚠️ Yes	✅ No

📖 Reference: MS article with additional details on this method

This method is just the Update User method with the specific attribute set. It will allow an application to disable or enable a guest user account in PwC's Entra ID tenant.

When enabling or disabling an account you must specify the User Object ID.

Sample Code

Lock account

PATCH https://graph.microsoft.com/v1.0/users/{id}
{
"accountEnabled": false
}

---

Add / Remove Guest Account Sponsor / Owner

Required API Permissions

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.ReadWrite.All	⚠️ Yes - All Territories	⚠️ Yes	⚠️ Yes

📖 Reference: MS article with additional details on this method

This method will allow an application to add a user and a guest account sponsor.

Sample Code

Add Sponsor

POST https://graph.microsoft.com/v1.0/users/{id}/sponsors/$ref 
{ 
  "@odata.id": "https://graph.microsoft.com/v1.0/users/{id}" 
} 

Delete Sponsor

DELETE https://graph.microsoft.com/v1.0/users/{user-id}/sponsors/{directory-object-id}/$ref 

Note

If /$ref is not appended to the request and the calling app has permissions to manage the sponsor object type, the sponsor object is also deleted from Microsoft Entra ID

---

Create Group

Required API Permissions

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
Group.Create	✅ No	⚠️ Yes	✅ No

📖 Reference: MS article with additional details on this method

This method will allow an application to create an Entra ID Security Group.

Note

Entra ID/M365 supports multiple types of groups. Only Security Groups can be created via Graph API. Graph API supports read-only for the other group types (Mail Enabled Security Groups, M365 Groups and distribution groups).

Sample Code

Create a security group and specify owner

POST https://graph.microsoft.com/v1.0/groups 
{ 
  "description": "Test Group with designated owner", 
  "displayName": "TestGroup123", 
  "groupTypes": [ 
  ], 
  "mailEnabled": false, 
  "mailNickname": "TestGroup123", 
  "securityEnabled": true, 
  "owners@odata.bind": [ 
    "https://graph.microsoft.com/v1.0/ users/{id}" 
  ] 
} 

---

Update Group

Required API Permissions

By default, an application/SPN has rights via Graph API to update groups the SPN has been assigned owner, so no elevated API permissions are needed.

📖 Reference: MS article with additional details on this method

This method will allow an application to update an Entra ID Security Group. With Security Groups, the only attribute you can update with this API is the group name/displayName. For adding or removing group members or owners, see other sections in this document.

When updating a group, you must specify the Group Object ID in Entra ID

Sample Code

Update Group

PATCH https://graph.microsoft.com/v1.0/groups/{id}
{
"displayName": " TestGroup567"
}

---

Add Group Owner

Required API Permissions

By default, an application/SPN has rights via Graph API to update groups the SPN has been assigned owner, so no elevated API permissions are needed. However, to see users and current members you need the following API permissions:

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.Read.All	✅ No	⚠️ Yes	✅ No
Groupmember.Read.All	⚠️ Yes - Regional CISOs	⚠️ Yes	⚠️ Yes

📖 Reference: MS article with additional details on this method

This method will allow an application to add a new group owner on an Entra ID Security Group.

When updating a group owner, you must specify the Group Object ID in Entra ID, as well as the Object ID of the user being added as an additional owner.

Sample Code

Add group owner

POST https://graph.microsoft.com/v1.0/groups/{id}/owners/$ref 
{ 
  "@odata.id": "https://graph.microsoft.com/v1.0/users/{id}" 
} 

---

Remove Group Owner

Required API Permissions

By default, an application/SPN has rights via Graph API to update groups the SPN has been assigned owner, so no elevate API permissions are needed. However, to see users and current members you need the following API permissions:

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.Read.All	✅ No	⚠️ Yes	✅ No
Groupmember.Read.All	⚠️ Yes - Regional CISOs	⚠️ Yes	⚠️ Yes

📖 Reference: MS article with additional details on this method

This method will allow an application to remove a group owner from an Entra ID Security Group. Once owners are assigned to a group, the last owner (a user object) of the group cannot be removed.

When deleting a group owner, you must specify the Group Object ID in Entra ID as well as the Object ID of the user being deleted as an owner.

Sample Code

Remove group owner

DELETE https://graph.microsoft.com/v1.0/groups/{id}/owners/{id}/$ref 

---

Add Group Member

Required API Permissions

By default, an application/SPN has rights via Graph API to update groups the SPN has been assigned owner, so no elevated API permissions are needed. However, to see users and current members you need the following API permissions:

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.Read.All	✅ No	⚠️ Yes	✅ No
Groupmember.Read.All	⚠️ Yes - Regional CISOs	⚠️ Yes	⚠️ Yes

📖 Reference: MS article with additional details on this method

This method will allow an application to add a member to a Security Group in Entra ID. When adding a group member, you must specify the Group Object ID in Entra ID as well as the Object ID of the user being added.

Sample Code

Add group member

POST https://graph.microsoft.com/v1.0/groups/{group-id}/members/$ref 
{ 
  "@odata.id": "https://graph.microsoft.com/v1.0/directoryObjects/{id}" 
} 

To add multiple members at a time; up to 20 members can be added to a single request:

Add multiple members to a group

PATCH https://graph.microsoft.com/v1.0/groups/{group-id} 
{ 
  "members@odata.bind": [ 
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}", 
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}", 
    "https://graph.microsoft.com/v1.0/directoryObjects/{id}" 
    ] 
} 

---

Remove Group Member

Required API Permissions

By default, an application/SPN has rights via Graph API to update groups the SPN has been assigned owner, so no elevate API permissions are needed. However, to see users and current members you need the following API permissions:

Permission	CISO Approval Required	ARR Required	SNow IRM Exception Required
User.Read.All	✅ No	⚠️ Yes	✅ No
Groupmember.Read.All	⚠️ Yes - Regional CISOs	⚠️ Yes	⚠️ Yes

📖 Reference: MS article with additional details on this method

This method will allow an application to remove a member to a Security Group in Entra ID.

nNte

If /$ref is not appended to the request and the calling app has permissions to manage the member object type, the member object will also be deleted from Microsoft Entra ID; otherwise, a 403 Forbidden error is returned.

For example: an app with both GroupMember.ReadWrite.All and User.ReadWrite.All permissions will delete a user.

Sample Code

Remove group member

DELETE https://graph.microsoft.com/v1.0/groups/{group-id}/members/{directory-object-id}/$ref

---

References

Name	Description
Overview of Microsoft Graph	Graph API overview
Working with Users in Microsoft Graph	Users' Graph API resources for developers
Identity GUM API 2.0 Guide	API guide for developers
Identity GUM SDK Reference Guide	SDK for developers