Instructions
To start using Jira Server for Microsoft Teams, you need to install both the Jira Server app from Microsoft Teams Apps menu and Microsoft Teams for Jira Sever app (add-on) for your Jira Server instance.
Note: Jira Server connector doesn’t require Jira app (add-on) installation, it should be configured manually by Jira administrator.
Prerequisites for installing App in Microsoft Teams
- Office 365 (it should be Office 365 with Business license or Enterprise Office 365 and IT admin has to enable Microsoft Teams in Office 365)
- Allow external apps in Microsoft Teams for Office 365 should be set to On. IT admin has to enable it in the Admin center going to Settings → Services & add-ins → Microsoft Teams → choose Apps → Allow external apps in Microsoft Teams → On. Please mind that after enabling the external apps in Office365, synchronization may take several hours.
Installing into Teams
Note: To install Jira Server app for Microsoft Teams, you need to have permissions from your Office 365 administrator to install third-party apps.
In your Microsoft Teams, go to “Apps” menu in bottom-left corner. Search for “Jira Server”, click the tile and follow the installation dialog.
The installation provides the following capabilities within Microsoft Teams:
- Connector
- Messaging Extension
- Bot
- Team and personal tabs
Connector
Connector is a capability that provides one-way communication from Jira Server to Microsoft Teams via webhooks. You can add connector to your Microsoft Teams channel from channel menu, like this:
On the connector configuration page, you will see the instructions and the webhook URL. Following the instructions, you need to create a webhook from your Jira Server instance. This can be done from “Administration” → “System” → “Webhooks”. Paste the webhook URL from connector configuration into Jira webhook and save. Finish by adding the connector in Microsoft Teams. You should receive a channel notification from connector telling that the connector has been added.
Jira ID
Jira ID is a unique identifier that is generated after Jira app (add-on) installation. If Microsoft Teams for Jira app (add-on) is installed in your Jira and you have the administrator permissions, you can see the Jira ID at the bottom of the configuration page in Jira. In case you don’t have administrator permissions, please contact your Jira administrator to provide you with the Jira ID from the add-on configuration page.
Messaging Extension
Note:Microsoft Teams for Jira app (add-on) is required for Jira Server messaging extension capability to work.
All your messaging extensions can be open from the bottom of the compose box. There are some native messaging extensions, such as Emoji, Giphy, and Sticker. Choose the More Options(⋯) button to see Jira Server and other messaging extensions. You can also pin Jira Server messaging extension so that you don’t have to select it from options menu every time.
Once you open the messaging extension, click “Sign In” to connect to your Jira instance. You will be asked to provide Jira ID.
When you paste the correct Jira ID, your next step will be to enter your Jira login credentials for authentication. After that, in the messaging extension you should see the search field and the list of recent issues from Jira. You’re all set!
Bot
Bot is another capability of Microsoft Teams. The Jira Server bot will be your personal assistant when working with Jira.
To start your interaction with the bot, click “Open” in front of “Bot” on installation screen, or simply search “Jira Server” in your main search area of Microsoft Teams at the top, and open Jira Server Bot.
To see which commands are available for you, type “help” in your conversation with the bot.
For most of the commands, the bot will ask you to authorize in Jira. To do that, you need to enter the “connect” command and following the dialog, paste your Jira ID and login credentials.
Team and personal tabs
Jira Server tab capability lets you pin your team’s backlog to your channel so that all the team members can see and manage it directly from Microsoft Teams.
There are also pre-defined personal tabs available in your Jira Server app, where you can quickly navigate to issues assigned to you, reported by you, or your issues report with your custom filter applied.
In order to see and interact with the tab, you or your teammates will be asked to authorize in Jira. This can be done by clicking the “Sign in” button on the tab and follow the dialog.
Installing Jira Server app (add-on)
To install the Jira Server app (add-on), you require Jira admin permissions. Under your admin account, sign in to your Jira Server instance and do the following:
- Navigate to "Administration" → "Applications" in the upper-right corner in Jira.
- Select “Application links” option under “Integrations” menu.
- Type in " https://jira-server.msteams-atlassian.com/" in the link form and click the "Create new link" button.
- You might receive a warning that " No response was received from the URL you entered". Ignore it and click "Continue".
- On the first screen of the Link applications dialog, enter "Microsoft Teams" to
the Application Name field and select the "
Create incoming
link" checkbox. Click "Continue".
- On next screen of the Link applications dialog, enter the following consumer details:
- Consumer key enter "OauthKey" as a value
- Consumer name enter "MicrosoftTeamsIntegration" as a value
- Public key which you can copy from app (add-on) configuration screen in a box. Use the following example:
- Click "Continue". You should end up with an application link that looks like
this:
Now the configuration is set.
In Jira app (add-on), at the bottom of the configuration screen, you will see the following Jira
ID:
The Jira ID will be requested from Microsoft Teams users during authentication. Share this ID with your Microsoft Teams users.
Configuring firewall
Jira Server for Microsoft Teams uses multiple Microsoft Azure services behind-the-scenes, and they must be reachable from your network. Despite the user’s location, all of the following IP/hosts should be whitelisted:
- login.botframework.com (Bot authentication)
- login.microsoftonline.com (Bot authentication)
- *.botframework.com (Bot channels)
- westus.api.cognitive.microsoft.com (for Luis.ai NLP integration)
- state.botframework.com (Bot state storage)
- cortanabfchanneleastus.azurewebsites.net (Cortana channel)
- cortanabfchannelwestus.azurewebsites.net (Cortana channel)
Authorization
Starting with version 1.4 Jira Server for Microsoft Teams (Jira Server application 2019.10.20 released on 2019-10-21) uses pure OAuth 1.0a authentication flow.
It requires the end-user to authenticate in Jira Server, allow using her credentials to authenticate as her in future, and provide generated verification code to Microsoft Teams.
Jira Server for Microsoft Teams does not process and store Jira user passwords.
Version 1.4x and above:
To successfully authenticate in app it's required for user to have direct network access to Jira Server. This may mean connecting VPN or doing this inside work subnet where Jira Server is hosted. Please note this is valid only for authentication process and is not needed further for other workflows.
Revamped process now consists of 9 stages:
-
Enter Jira id in Microsoft Teams. Click “Connect”.
-
On the next screen click on the “Authorize” link. It has the following format: https://
/jira/plugins/servlet/oauth/authorize?oauth_token= . 
-
It will either open Jira login page or redirect you to third-party identity provider like Azure Active Directory. Please put your credentials and log in.
-
You will be redirected to Jira authorization page asking to allow Microsoft Teams to access to your data in Jira.
Note you do not pass and store password in our app.
-
Click “Allow”. You will be redirected to “Access Approved” Jira page.
- Look for verification code and copy it. Note this page can be displayed in a locale selected in your Jira profile and verification code may have other punctuation signs other than apostrophes around it.
-
Paste the verification code to a respective field in Microsoft Teams.
- Click “Continue”. If the code is correct, you will be redirected to “Authentication successful” page and popup should close.
- You are all set and can manage your Jira issues in Microsoft Teams.
Additional notes:
- - if you want to change Jira user or stop working with the integration completely, feel free to use ‘Sign out’ functionality in tabs and ‘disconnect’ bot command
- - if you previously granted Microsoft Teams access to Jira data, there is no need to re-authorize, everything would work just fine after the release
- - if you are trying to authenticate with an old Microsoft Teams for Jira Server app version, you’ll get a warning after ‘Connect’ step asking to contact your Jira administrator to update the app to the most recent version
Frequently asked questions
In this section we have gathered the most common requests to our support team and obstacles that users can face working with the app. You might find the answers to your questions here. You may also reach to our support team via the contact form here in case you still have questions.
Where do I find my Jira ID?
Jira ID is unique identifier that is generated after Jira app (add-on) installation.
After Microsoft Teams for Jira app (add-on) is installed in your Jira and you have the administrator permissions, you can see the Jira ID at the bottom of the app configuration page in Jira.
In case you don’t have administrator permissions, please contact your Jira administrator to provide you with the Jira ID from the add-on configuration page.
How do I connect the app to my Jira?
To connect your Microsoft Teams app to your Jira, you need to make sure
- the Jira app (add-on) “Microsoft Teams for Jira” is installed in your Jira instance
- Application Link is configured
If the add-on is installed, in your Microsoft Teams app you will be asked to provide Jira ID – the unique ID generated by the add-on. Once you enter the Jira ID, you will have to authenticate into your Jira server instance.
How do I revoke my access in Jira?
To revoke app access to your Jira instance, do the following:
In your Jira, go to Profile → Tools → View OAuth Access Tokens → find MicrosoftTeamsIntegration and click “Revoke Access”.
Does the app store Jira login details I have entered?
The app uses OAuth 1.0 to authenticate the user. The app doesn’t store or collect user’s login details.
Can I use the app without Jira admin rights?
Yes, you can use the app if admin has already set up the add-on in Jira and shared Jira ID with you. However, you won’t be able to install it without admin rights.
Does everyone within the channel see the data I’m sharing through the app?
If you interact with the bot, everyone can see the replies and data that bot sends into the channel. Also, if you share Jira Issues through messaging extension it is visible for others in the channel or conversation. However, if you add Jira Server tab to your channel, then the other teammates will have to authorize to see the tab contents.
I don’t receive notifications from Jira Server connector.
If you configured the Jira Server connector in your channel and don’t receive notifications, from Jira, the following steps might help you:
- Check if the connector is added into Microsoft Teams channel. Go to Configured → Find “Jira Server”
- If you have Jira administrator permissions, go to Administration menu → System → Webhooks and make sure the webhook for this connector is added. The webhook URL should start as this https://connectors.msteams-atlassian.com/JiraServer/...
There are a lot of IPs that needed to be whitelisted. Is it possible reduce the list?
No, in order for the application to work properly, all the IPs from the list should be whitelisted in your system. The IPs for whitelist required by the Microsoft Azure services that are running on the backend. You may find IP details for whitelist from official source here.
I’m having error on authorization step in Microsoft Teams when connecting to my Jira instance. What should I do?
Try re-installing both Microsoft Teams for Jira app and Microsoft Teams add-on in your Jira instance. Also, please make sure you use the latest version of the add-on from Marketplace. If the issue persists - reach out to our support team.
I have sent an email to the support team but there is no reply.
You should get the reply within 16 business hours. In case this time has passed and nobody reaches back to you - please, check your spam filter configuration or try to re-submit email from different email address.
I don’t see Jira Server / Jira Cloud / Confluence / Bitbucket app in “Apps” menu in my Microsoft Teams. How can I install them?
Most likely you don’t have permissions to install 3rd-party apps in your Microsoft Teams tenant. Contact your Office 365 admin to help you installing the needed app.
Where do I find Jira add-on configuration?
After the add-on is installed in your Jira instance, you can find the configurations under Administration -> Manage Apps -> Microsoft Teams for Jira Server. Please note, “Administration” menu is only available for the Jira admins.