Microsoft 365 for Jira

BetaThis is a live doc! Anyone with edit access can make updates in real time without having to publish.

By Tobias Viehweger

Why is an approval needed?

Using our app requires delegated access to Microsoft 365, via the Microsoft Graph API. We use the most common form of delegated authentication flow, the authentication code flow via an Enterprise application. In many cases, access to Microsoft Graph resources is restricted by default. If you can’t login from Jira or Microsoft Teams, your Microsoft 365 or Azure administrator might need to consent to the app for you.

In case you are interested in the exact permissions and why we need them, please check out this dedicated permissions article.

Technical ids & scopes

Below you can find a list of necessary client ids and scopes. You only need to allow the Enterprise apps in case the feature should be used. Depending on the feature, there are also optional scopes which enhance the basic functionality, but are considered optional by us and can be omitted if not required - the app will gracefully handle the missing scopes.

The following base scopes are required for all features:

1email
2offline_access
3profile
4openid

App feature	Enterprise app client id	Scopes
Email	e7185a25-9df9-4d05-b779-76b04bf46424	`1Mail.ReadWrite.Shared 2Mail.Send.Shared 3People.Read 4User.Read 5User.ReadBasic.All` Approve for all users
Meetings	e7185a25-9df9-4d05-b779-76b04bf46424	`1Calendars.ReadWrite 2Calendars.ReadWrite.Shared 3MailboxSettings.Read 4OnlineMeetings.ReadWrite 5People.Read 6User.Read 7User.ReadBasic.All` Approve for all users optional Necessary for certain features to work, e.g. searching for rooms `1Place.Read.All` Approve for all users (incl. optional)
Calendar	e7185a25-9df9-4d05-b779-76b04bf46424	`1Calendars.ReadWrite 2Calendars.ReadWrite.Shared 3MailboxSettings.Read 4OnlineMeetings.ReadWrite 5People.Read 6User.Read 7User.ReadBasic.All` Approve for all users optional Necessary for certain features to work, e.g. searching for rooms & embedding Teams channel calendars `1Place.Read.All 2Group.ReadWrite.All 3Team.ReadBasic.All` Approve for all users
To Do	32d752a1-8945-4600-97c9-73ed32c3627a	`1Tasks.Read 2Tasks.ReadWrite 3Tasks.ReadWrite.Shared 4User.Read` Approve for all users
Teams	89d5ca9f-d63b-4885-bd30-6e7433c1540c	`1Channel.ReadBasic.All 2ChannelMessage.Send 3Chat.ReadWrite 4Team.ReadBasic.All 5User.Read 6User.ReadBasic.All 7Presence.Read.All` Approve for all users
Teams JSM portal	a47ed889-74d6-4acf-b5c8-b1172696eb70	`1User.Read` Approve for all users
Teams JSM portal notifications	89d5ca9f-d63b-4885-bd30-6e7433c1540c	`1TeamsTab.Create 2AppCatalog.Read.All 3TeamsAppInstallation.ReadWriteForChat` Since the portal link is an individual link we can’t provide a direct link to approve for all users. Feel free to see our docs to get the direct link: Approve for all users

Approving access for all users for our apps

To approve access for all users for the relevant apps, please send your Office 365 administrator the following links or use the links above. In this case your admin has to approve for every app separately.

App feature	Approval link
Email	https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=e7185a25-9df9-4d05-b779-76b04bf46424&state=no&redirect_uri=https%3a%2f%2fatlassianconnect.yasoon.com%2fauth-success.html&scope=email%20offline_access%20profile%20openid%20Mail.ReadWrite.Shared%20Mail.Send.Shared%20People.Read%20User.Read%20User.ReadBasic.All
Meetings	https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=e7185a25-9df9-4d05-b779-76b04bf46424&state=no&redirect_uri=https%3A%2F%2Fatlassianconnect.yasoon.com%2Fauth-success.html&scope=email offline_access profile openid Calendars.ReadWrite Calendars.ReadWrite.Shared MailboxSettings.Read OnlineMeetings.ReadWrite People.Read User.Read User.ReadBasic.All With room support https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=e7185a25-9df9-4d05-b779-76b04bf46424&state=no&redirect_uri=https%3A%2F%2Fatlassianconnect.yasoon.com%2Fauth-success.html&scope=email offline_access profile openid Calendars.ReadWrite Calendars.ReadWrite.Shared MailboxSettings.Read OnlineMeetings.ReadWrite People.Read User.Read User.ReadBasic.All Place.Read.All
Calendar	Only mandatory scopes: https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=e7185a25-9df9-4d05-b779-76b04bf46424&state=no&redirect_uri=https%3A%2F%2Fatlassianconnect.yasoon.com%2Fauth-success.html&scope=email offline_access profile openid Calendars.ReadWrite Calendars.ReadWrite.Shared MailboxSettings.Read OnlineMeetings.ReadWrite People.Read User.Read User.ReadBasic.All With Teams channel calendar, group & room support https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=e7185a25-9df9-4d05-b779-76b04bf46424&state=no&redirect_uri=https%3A%2F%2Fatlassianconnect.yasoon.com%2Fauth-success.html&scope=email offline_access profile openid Calendars.ReadWrite Calendars.ReadWrite.Shared MailboxSettings.Read OnlineMeetings.ReadWrite People.Read User.Read User.ReadBasic.All Place.Read.All Group.ReadWrite.All Team.ReadBasic.All
To Do	https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=32d752a1-8945-4600-97c9-73ed32c3627a&state=no&redirect_uri=https%3a%2f%2fatlassianconnect.yasoon.com%2fauth-success.html&scope=email%20offline_access%20profile%20openid%20Tasks.Read%20Tasks.ReadWrite%20Tasks.ReadWrite.Shared%20User.Read
Teams	https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=89d5ca9f-d63b-4885-bd30-6e7433c1540c&state=no&redirect_uri=https%3A%2F%2Fatlassianconnect.yasoon.com%2Fauth-success.html&scope=email offline_access profile openid Channel.ReadBasic.All ChannelMessage.Send Chat.ReadWrite Team.ReadBasic.All User.Read User.ReadBasic.All Presence.Read.All
Teams JSM portal	https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=a47ed889-74d6-4acf-b5c8-b1172696eb70&state=no&redirect_uri=https%3a%2f%2fatlassianconnect.yasoon.com%2fauth-success.html&scope=email%20offline_access%20profile%20openid%20User.Read

Your admin will see the following screen, where the permissions can be confirmed.

Please note, that despite what the screen says in the subtext, we won’t get access to all user resources automatically after approving this. Before we can get access to any Office data, the users will need to log in with their own account as well from Jira.

Approving access for a limited set of users

Using Entra ID configurations

Please go to https://entra.microsoft.com/ → Applications → Enterprise applications and search for our apps.

There are basically three steps to allow the app only for certain users:

Make assignment of the app required. This way only assigned users will be able to login in the first place.
Assign the relevant users to the app
Grant admin consent for the app for the organization

→ Only the assigned users can login and don’t need to ask for approval:

Using Powershell

In case you only want to approve the access for a limited set of users, e.g. you already have a dedicated AzureAD group for Jira users, you’ll need to do this via a Powershell script. The easiest way is to create a new .ps1 file on your computer and paste the following code. Make sure to adjust the client ids and scopes according to the table above.

1# Install Microsoft Graph Powershell toolkit
2Install-Module Microsoft.Graph -Scope CurrentUser
3
4# The app for which consent is being granted. In this example, we're granting access
5# to the Microsoft Teams Jira feature, use one of the following:
6# -----------------------------------------------------------------
7# Email               e7185a25-9df9-4d05-b779-76b04bf46424
8# Meetings            e7185a25-9df9-4d05-b779-76b04bf46424
9# Calendar            e7185a25-9df9-4d05-b779-76b04bf46424
10# To Do               32d752a1-8945-4600-97c9-73ed32c3627a
11# Teams               89d5ca9f-d63b-4885-bd30-6e7433c1540c
12# Teams JSM portal    a47ed889-74d6-4acf-b5c8-b1172696eb70
13$clientAppId = "89d5ca9f-d63b-4885-bd30-6e7433c1540c" # Teams
14
15# The permissions to grant. Here we're including "openid", "profile", "User.Read"
16# and "offline_access", "email" (for basic sign-in), as well as feature specific scopes
17# Email               @("openid", "profile", "offline_access", "User.Read", "email", "Mail.ReadWrite.Shared", "Mail.Send.Shared", "People.Read", "User.ReadBasic.All")
18# Meetings            @("openid", "profile", "offline_access", "User.Read", "email", "Calendars.ReadWrite.Shared", "OnlineMeetings.ReadWrite", "User.ReadBasic.All")
19# Calendar            @("openid", "profile", "offline_access", "User.Read", "email", "Calendars.ReadWrite", "Calendars.ReadWrite.Shared", "OnlineMeetings.ReadWrite", "People.Read", "User.ReadBasic.All", "Place.Read.All", "Group.ReadWrite.All", "Team.ReadBasic.All")
20# To Do               @("openid", "profile", "offline_access", "User.Read", "email", "Tasks.Read", "Tasks.ReadWrite", "Tasks.ReadWrite.Shared")
21# Teams               @("openid", "profile", "offline_access", "User.Read", "email", "Channel.ReadBasic.All", "ChannelMessage.Send", "Chat.ReadWrite", "Team.ReadBasic.All", "User.ReadBasic.All")
22# Teams JSM portal    @("openid", "profile", "offline_access", "User.Read", "email")
23
24# For Teams
25$permissions =  @("openid", "profile", "offline_access", "User.Read", "email", "Channel.ReadBasic.All", "ChannelMessage.Send", "Chat.ReadWrite", "Team.ReadBasic.All", "User.ReadBasic.All")
26
27# Step 0. Connect to Microsoft Graph PowerShell. We need User.ReadBasic.All to get
28#    users' IDs, Application.ReadWrite.All to list and create service principals, 
29#    DelegatedPermissionGrant.ReadWrite.All to create delegated permission grants, 
30#    and AppRoleAssignment.ReadWrite.All to assign an app role.
31#    Group.Read.All is necessary if you want to use users from a security group
32Connect-MgGraph -Scopes ("User.ReadBasic.All Application.ReadWrite.All " `
33                        + "DelegatedPermissionGrant.ReadWrite.All " `
34                        + "AppRoleAssignment.ReadWrite.All " `
35                        + "Group.Read.All")
36
37# Step 1. Check if a service principal exists for the client application. 
38#     If one does not exist, create it.
39$clientSp = Get-MgServicePrincipal -Filter "appId eq '$($clientAppId)'"
40if (-not $clientSp) {
41   $clientSp = New-MgServicePrincipal -AppId $clientAppId
42}
43
44Write-Host "Service principal for $($clientAppId) is $($clientSp.Id)"
45
46# Step 2. Define users that should have the app consented
47#         Either use a single, hard coded user (upn or GUID)
48$userIds = @((Get-MgUser -UserId "someuser@contoso.com").Id)
49
50#         Or assign app based on a security group
51# $userIds = Get-MgGroupMember -GroupId '<groupGuid>' -All | % {$_.Id } 
52
53# Loop over selected users
54foreach ($userId in $userIds)
55{
56    # Step 3. Create a delegated permission that grants the client app access to the
57    #     API, on behalf of the user. If the existing grant already exist, skip creating it
58    #     Note: In case of changed scopes, this is not updated automatically yet
59    $existingGrant = Get-MgOauth2PermissionGrant -Filter "consentType eq 'Principal' and principalId eq '$($userId)' and clientId eq '$($clientSp.Id)'" 
60
61    if (-not $existingGrant) {
62        $resourceSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"
63        $scopeToGrant = $permissions -join " "
64        New-MgOauth2PermissionGrant -ResourceId $resourceSp.Id `
65                                            -Scope $scopeToGrant `
66                                            -ClientId $clientSp.Id `
67                                            -ConsentType "Principal" `
68                                            -PrincipalId $userId
69        
70        # Step 4. Assign the app to the user. This ensures that the user can sign in if assignment
71        #     is required, and ensures that the app shows up under the user's My Apps.
72            # The app role ID 00000000-0000-0000-0000-000000000000 is the default app role
73            # indicating that the app is assigned to the user, but not for any specific 
74            # app role.
75        New-MgServicePrincipalAppRoleAssignedTo `
76                -ServicePrincipalId $clientSp.Id `
77                -ResourceId $clientSp.Id `
78                -PrincipalId $userId `
79                -AppRoleId "00000000-0000-0000-0000-000000000000"
80    }
81}

Creating the Enterprise application only for review purposes

In case you want to inspect the app first before approving is, you can just add the service principal to AzureAD.

Do do this, you’ll need to use Powershell to create it manually. For the “AppId” parameter, use one of the client ids listed in the table above, in this case the one for Teams.

1# Install Powershell module for Azure (if you don't have it yet)
2Install-Module AzureAD
3
4# Connect to Azure interactively
5Connect-AzureAD -Confirm
6
7# Create the new service principal 
8New-AzureADServicePrincipal -AppId 89d5ca9f-d63b-4885-bd30-6e7433c1540c -Tags {WindowsAzureActiveDirectoryIntegratedApp}

Afterwards, you should be able to find the enterprise app in the UI linked above, where you can restrict the application to certain users or groups, or, using the “Properties” page, allow users to self-approve the app:

References

https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-user-consent?tabs=azure-portal

https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-admin-consent-workflow

https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent