Pia's minimum Permissions for Microsoft App Registration
App Registrations/Authorizations
This section covers how the App Registration Authorization process works within Pia.
Step 1: When authorizing a client in Pia, each individual client needs separate authorization for Office 365/Azure. Start on the client dashboard as per screenshot below:
Step 2: This will take you to a Microsoft Page where you can sign in as a user who has access to Authorize Pia's App Registration.
Step 3: Once you have signed in, the list of permission Pia requests will be displayed. Click "Accept" to proceed.
Frequently Asked Questions
When I accept the authorization for Pia, where do I go to find a record of the authorization in my client's Azure tenant?
Once you have Authorized the App Registration, the app registration will be named like this: “Pia.CustomerPortal.Tenant.Prod.XXX.Consent”.
To see this in your client's Azure tenant, you can open the Enterprise App Settings in Azure and click to open which should look like below:
Do I need new admin account or can I use my existing admin account?
You should use your existing admin account. The main requirement for the account that you use to perform the authorization is that it must have access to authorize Apps (like Pia). This is typically a Global Admin role.
Does this mean that Pia will use the admin account or store the credentials for the admin account?
No, the authorize action only grants Pia access to your clients' Azure/Office365 tenant. The admin account you use is just granting this access (similar to how if you modify a permission in Azure, you need an admin account to do so). Pia does not store credentials for your admin account and Pia's access is not tied to the account you use for this part of the authorization process.
Application Scopes
Pia's authorization action grants a list of scopes which includes those that are used by automations provided by Pia and additional scopes which may be required for automations for custom development.
Below is the list of scopes that Pia requires at its bare minimum to perform its duties. You can revoke any other permissions on the App Registration itself if you wish to reduce Pia's access to the minimum set of scopes as defined below:
Microsoft Graph API
| Scopes | Description |
|---|---|
| AuditLog.Read.All | Used for Password reset and MFA status |
| Directory.ReadWrite.All | Used for actions in the directory, including Staff Onboarding/Offboarding, changing user details, etc. |
| Group.ReadWrite.All | Used for changing details of groups. |
| GroupMember.ReadWrite.All | Used to add/remove users to groups |
| Organization.ReadWrite.All | Used for confirming Licenses that are available in the Tenant |
| RoleManagement.ReadWrite.Directory | Used to add the App Registration to RBAC roles for Exchange/Teams/Sharepoint |
| ServiceHealth.Read.All | Used to read the service status of the tenant |
| Synchronization.ReadWrite.All | Used for Cloud Hybrid environments to see the status of Microsoft Entra Connect (originally Azure AD Connect), or to trigger manual syncs for Entra Cloud Sync. This can be revoked if not a Cloud Hybrid Client. |
| User.ManageIdentities.All | Used to modify attributes of a user identity |
| User.ReadWrite.All | Used to modify details of a user. E.g. Display name, Office location, etc. |
| UserAuthenticationMethod.ReadWrite.All | Despite its misleading name, this application-level scope only allows reading a user's authentication methods. Pia uses it to identify which methods a user has, but modifications or removals are only possible with the Delegated permission. |
Office 365 Exchange Online
| Scopes | Description |
|---|---|
| Exchange.ManageAsApp | Allows Pia to perform administration tasks in Exchange Online. |
How to guide on revoking permissions
All other scopes not specified above, can be revoked from the baseline set of permissions on the App Registration.
If you revoke a permission that is detailed in the list above, we cannot guarantee that all the automations provided by Pia will work.
If you accidentally revoke a permission, you will need to follow the “Restore revoked permissions” steps detailed in this article: Restore revoked permissions granted to applications in Microsoft Entra ID
The following Microsoft document details how to revoke permissions granted to applications – we won’t duplicate any information here as Microsoft may change this. Review permissions granted to applications - Microsoft Entra ID.
Delegating Access to Pia
Pia requires a small set of delegated Microsoft Graph permissions to run its automations.
The account used to grant delegation must remain unchanged after the delegation process. This is a requirement from Microsoft. This means:
- The assigned Entra ID role(s) must not be removed or modified.
- The account password must not be reset.
- The account must remain active and available for Pia to use.
Choose one of the following delegation options based on your security and operational requirements.
Option 1: Global Administrator (Recommended)
Use a Global Administrator account to grant the required delegated permissions.
This is the simplest and most reliable option because a Global Administrator can consent to all required permissions without requiring additional role configuration.
Option 2: Helpdesk Administrator + Authentication Administrator
Use an account assigned both the Helpdesk Administrator and Authentication Administrator roles.
Helpdesk Administrator & Authentication Administrator
The Helpdesk Administrator role in Azure Entra ID allows support staff to assist users with basic account management tasks, such as resetting passwords for non-admin users, reading and managing user profiles (except for admins), and viewing sign-in logs.
The Authentication Administrator role grants access to view, set, and reset authentication methods for non-admin users. It is essential for managing Multi-Factor Authentication (MFA) and other security settings3. However, it does not allow modifications for accounts with administrative roles.
Option 3: Privileged Authentication Administrator
Use an account assigned the Privileged Authentication Administrator role.
This is the least-privileged role that enables delegation for scenarios involving privileged accounts.
Privileged Authentication Administrator
The Privileged Authentication Administrator role in Azure Entra ID allows support staff to iew, set and reset authentication method information for any user (admin or non-admin)..
Granting delegation with a Global Administrator account does not give Pia Global Administrator permissions.
Pia can only access and perform actions within the specific delegated scopes listed below. The account used to grant delegation does not increase Pia's effective permissions.
As a result, once delegation has been completed, Pia's access is limited to the delegated scopes regardless of whether the consent was granted by a Global Administrator, a Privileged Authentication Administrator, or another supported role.
Microsoft Graph API
While the following scopes are available, not all scopes are used by Pia's out of box/standard set of automations. Refer to this article to view the minimum scopes that are required for Pia's standard/out of the box automations.
| Delegates | Description |
|---|---|
| Directory.AccessAsUser.All | Allows Pia to impersonate the account that is setup in the Delegates. |
| Calendars.ReadWrite.Shared | Allow the delegated account to manage calendars it has been given access to |
| Group.ReadWrite.All | Create/modify/delete groups and read all group properties and memberships |
| Mail.Read - (Requires an Exchange mailbox.) | This permission allows Pia to read mail only from the delegated account's mailbox, not other mailboxes in Exchange. |
| Mail.Send - (Requires an Exchange mailbox.) | Send mail as the Delegated Account. This account allow Pia to send emails using your own company domain for certain automations and notifications as part of the normal operation of your Pia tenant. This means that the account must be licensed with a mailbox. |
| User.Read | This permission allows users to sign-in to Pia, and allows Pia to read the profile of signed-in users. It also allows Pia to read basic company information of signed-in users. |
| UserAuthenticationMethod.ReadWrite.All | Pia can reset or change Multi-Factor Authentication (MFA) and modify privileged attributes like a user's mobile number. To perform these tasks, the delegated account must have at least the Privileged Authentication Administrator role or a custom role with equivalent permissions. More details on permissions can be found in this Microsoft article. |
| offline_access | This permission allows Pia to maintain access to data you have given it access to. The offline_access is an OpenID Connect (OIDC) scope. |
Windows Azure Service Management API
| Delegates | Description |
|---|---|
| user_impersonation | This permission allows the delegated account to impersonate a user for Azure services but will only have access to the Azure subscriptions explicitly granted in Azure AD. This access can be revoked if Azure management is no longer needed. |
Microsoft Teams
| Delegates | Description |
|---|---|
| user_impersonation | This permission allows the delegated account to impersonate a user for Azure services but will only have access to the Teams services it has been explicitly given access to. This access can be revoked if Teams Management is no longer needed. |