How IT professionals can control Microsoft Graph API Permissions & Scopes (Outlook, Calendar, Teams, etc)

Sometimes you don’t want JobScore to access Microsoft programs, often for security or compliance reasons. This means you’ll need to restrict access to some Microsoft services for some users.

There are multiple ways to do this, but before we get into them, here’s a summary of the top concerns we’ve heard from employers about letting JobScore access your data:

Common Concerns

Calendar read and write access: JobScore shows people’s free/busy information and allows people to schedule interviews. To keep things simple, JobScore respects all of Microsoft’s built in calendar data-access controls.

• Example: If user 1 tries to see user 2’s free/busy status to schedule an interview, JobScore only shows the information user 1 can normally see in their Outlook Calendar.

• So, if you have calendar permissions set up the way you want, everything should be fine as JobScore mirrors what’s already happening in Outlook.

• JobScore does not store any externally created event data in the system, events are only shown to registered users to be able to find available interview timeslots.

Email read access: JobScore uses the Mail.ReadWrite scope to facilitate collaboration and create a “single source of recruiting truth” by synchronizing the emails exchanged between your employees and candidates.  This means everyone involved in the hiring process can easily see the correspondence other people have exchanged with a candidate, making recruiting faster, easier, and less error-prone. The ability for JobScore to read emails is turned OFF by default. Individual users must specifically choose to turn it on.

• Example: If user 1 has email sync turned on, the messages they exchange with candidates will appear in JobScore, so user 2 can see the emails sent back and forth between user 1 and candidates. Normally user 2 would be unaware of these messages because they would be locked up in user 1’s Outlook email.

• The concerns here are typically twofold:

  • The only way to make this feature work is to give JobScore rights to read all of a user’s emails. The fact that JobScore only stores emails exchanged with candidates might not matter because your policies dictate that no one outside your firm can access this data. If it makes a difference, to help alleviate security concerns JobScore is SOC2 type 2 certified

  • There is a concern that some candidate email correspondence will be made public that should not. To alleviate this concern, JobScore includes the ability to make emails private.

Access control options

To control access, first you’ll need to decide which app you want to use:

• The Microsoft Account App, which enables integrations for all users on your domain who use JobScore. 

• The Microsoft User App, which is individually installed by each user.  The User App is missing some unique features your team may need.

If you install the Account App for everyone:

• You can turn off email sending and reading on the Edit Microsoft Account Settings page in JobScore.

  • If you turn things off in this way JobScore will still have access to related scopes, but they will not be used, and the JobScore features they power are turned off.  So, for instance, if you aren’t sure if you need email features, this method allows business users to turn features on and off easily with a click.  Users with the owner and admin access levels can adjust these settings here >>

• You can turn off specific scopes for all users in the Microsoft Azure Portal.

  • This allows IT departments to prohibit JobScore from using specific APIs no matter what anyone does.  Choose this option if you need a bulletproof mechanism to ensure JobScore can’t access specific data or perform specific actions. To complete this step you’ll need to first identify which Account App permission to remove, and then follow the appropriate set of instructions depending on whether it’s an application permission or delegated permission.

• You can control which users can access JobScore using groups in the Microsoft Azure Portal.

  • When you install the Account App, turn ON Single Sign-On (SSO), and turn OFF the ability for users to login using a password on the Edit Microsoft Account Settings page, you can control who can log in to JobScore and who can’t using groups.  For instance, you could allow JobScore to be used by people in the HR and Sales departments, but exclude the executive team.  The downside of this approach is that if someone needs to use JobScore and they are not in the appropriate group, you’ll need to update settings user-by-user. Read the instructions here >>

If you prefer to have your team install the User App one by one:

• Users with the owner access level can control which scopes are granted on the Control Microsoft User App Scopes page in JobScore:

  • This allows you to block every user granting access to a specific scope if needed.  Start by identifying which User App permissions you want to remove then update the User App scopes on this page in JobScore.

• You can turn off specific scopes using the Microsoft Azure Portal.

  • This allows IT departments to prohibit JobScore from using specific APIs no matter what anyone does.  Choose this option if you need a bulletproof mechanism to ensure JobScore can’t access specific data or perform specific actions. To complete this step you’ll need to first identify which  User App permission to remove, and then follow the instructions to revoke delegated permissions.

Account App Permissions

The JobScore Microsoft Account App requests the following permissions by default:

User App Permissions

The JobScore Microsoft User App requests the following permissions by default:

How to revoke Microsoft Application permissions for the Account App

To complete these steps you must be a Global Admin in your Microsoft Account.

Step 1

Start by logging into Powershell for your domain. Run the commands below to get the AppRoleAssignmentID for the permissions(s) you wish to revoke.

Install-Module -Name AzureAD

Import-Module AzureAD
Connect-AzureAD

$sp = Get-AzureADServicePrincipal -Filter "displayName eq 'JobScore'"
$spId = $sp.ObjectId

$assignedRoles = Get-AzureADServiceAppRoleAssignedTo -ObjectId $spId

$assignedRoles | ForEach-Object {
$role = $_
$roleId = $role.Id
$resourceId = $role.ResourceId

$servicePrincipal = Get-AzureADServicePrincipal -ObjectId $resourceId

$item = $servicePrincipal.AppRoles | Where-Object { $_.Id -like $roleId }

[PSCustomObject]@{
AppName = $role.PrincipalDisplayName
Permission = $item.Value
Description = $item.DisplayName
AppRoleAssignmentId = $role.ObjectId
}
} | Format-Table -AutoSize

Step 2

Run the command below to revoke a permission. Please cut-and-paste in the AppRoleAssignmentId you found in step 1 where it says “Value”

Remove-AzureADServiceAppRoleAssignment -ObjectId $spId -AppRoleAssignmentId "Value"

When you successfully revoke a permission there is no verification message returned in powershell. It should look like this:

If you need to revoke more than one permission, repeat the command for each AppRoleAssignmentId. 

When done, if you wish to verify which permissions are still active, please repeat the commands in step 1 above.

How to restore revoked application permissions

If you need to restore a revoked permission, please uninstall and reinstall the JobScore Microsoft Account App to reset everything and start over.  Then repeat steps 1 and 2 until you reach your desired state.

How to revoke Microsoft Delegated permissions

To complete these steps you must be a Global Admin in your Microsoft Account.

Step 1

Start by logging into the Microsoft Graph Explorer and make a GET request to fetch the application. For the Account Application, run this request:

GET https://graph.microsoft.com/v1.0/servicePrincipals?$search="displayName:JobScore"&$select=id,displayName

For the User Application, run this request:

GET https://graph.microsoft.com/v1.0/servicePrincipals?$search="displayName:JobScore User"&$select=id,displayName

You will see something like this:

Find the item in the list with the displayName you are looking for: either "JobScore" or "JobScore User". Write down the "id" above the displayName.  You’ll need this in the next step.

Step 2

Make a GET request for oauth permission grants:

GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants

Scroll down until you find the “ClientID” in the list that matches the “id” you found in step 1.

 Below the clientID you will see another value called “id” - this is the value you need to use in step 3.

Step 3

Make the PATCH request to revoke permissions.

• Copy and paste the code below into the Microsoft Graph Explorer when logged in as a user that is a Global Admin for your account.

• Replace the “Value” at the end of the URL with the “id” you just retrieved in step 2

• Edit “scope” to only include the permissions that you wish to keep active.  So, to remove the Mail.Send permission for the User App, you’d simply delete it from the text below and make the request.

To edit the Account App paste this:

PATCH https://graph.microsoft.com/v1.0/oauth2PermissionGrants/Value

Body:
{ "scope": "Calendars.ReadWrite.Shared User.Read Group.ReadWrite.All
Directory.ReadWrite.All" }

To edit the User App, paste this:

PATCH https://graph.microsoft.com/v1.0/oauth2PermissionGrants/Value

Body:
{ "scope": "Calendars.Read.Shared Calendars.ReadWrite Contacts.Read Mail.ReadWrite
Mail.Send OnlineMeetings.ReadWrite User.Read User.ReadBasic.All" }

When you’ve successfully removed a delegated permission, you’ll see something like this:

How to restore revoked delegated permissions

To restore permissions, complete steps 1 to 3 above and edit the list of scopes in the final step to include all of those you wish to be enabled. If you want everything enabled just run the command as-is.

If, for some reason, none of these options will meet your business needs, feel free to contact [email protected] explaining what you need and we’ll do our best to help you out.

How to use Groups to control JobScore user access

To complete these steps you must be a Global Admin in your Microsoft Account.

Visit the Edit Microsoft Account Settings page and turn ON Single Sign-On (SSO), and turn OFF the ability for users to login using a password:

After you install the Microsoft account app visit this page in your azure portal: Enterprise Applications > JobScore > Properties and make sure the “Assignment Required” setting is set to yes:

Next click on the "Users and groups" tab on the left and and add the groups (or users) who you want to be able to access JobScore: