Pia's minimum Permissions for Microsoft App Registration

Pia requests a lot of permission when being setup and you may have a client that wants to understand or has hard limits on granting privileged access. This article is to help cover off more information around the minimum permissions Pia requires to run automations.

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

1. 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:

   

2. 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.

3. 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.

note 1

If you revoke a permission that is detailed in the list above, we cannot guarantee that all the automations provided by Pia will work.

note 2

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.

Required Delegates

Pia requires a handful of delegated scopes listed below in order to run its automations. The accounts used to grant delegation must remain intact as they were when delegating. This means that the roles cannot be changed and the password cannot be reset.

We recommend using a global administrator account however, we have tested and confirmed delegating the below permissions with the roles - Helpdesk Administrator and Authentication Administrator will be enough permission for Pia's out of the box automations to work on non-privileged accounts.

Important

Even if you use a Global Administrator account to delegate access to Pia, Pia will still ONLY have access that you have delegated which will be a narrow scope of permissions as defined below. From Pia's perspective, it means there is no difference whether you use a Helpdesk/Authentication Administrator user or Global Administrator user to grant the access.

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.

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.