During my time at Atlassian, many Jira administrators have asked, “How do I share Jira with external partners in my development process?”. External partners can integrate alongside your internal teams with Jira. This article targets external partners who fully engage in the development process. Collaborative teams or agencies that need to give clients visibility into the work stream can benefit from a shared instance of Jira. I’m making an assumption that this Jira instance is solely for working with external partners. You can easily extend the principles in this article to build a shared Jira instance that hosts internal as well as external development.
Step 1: Define your user base
In many organizations, the IT group manages an LDAP or Active Directory server that controls the login for all internal employees. When on boarding a large number of external users, a separate directory structure may be the right way to go. Jira (or Crowd) can store log in accounts for all of your external partners. Why use Crowd? Crowd is a full fledged single sign-on server. If you’re just planning on using Jira and Confluence in a smaller instance, Jira can provide authentication service.
If I can give one piece of advice, it’s to think about how your system will grow, and build a structure that will be flexible to growth. Your directory structure and group layout will be the core infrastructure by which you configure Jira and give access. Teams in Space is our demo company that works with several external partner engineering teams. Let’s take a look at how Teams in Space builds a shared Jira instance at mars.example.com. Around the office the server is known as “mars.” 
Working from the top, the first layer indicates the directories you’ll need to connect to Jira. The red groups come from your corporate directory structure (Active Directory, LDAP, etc). The blue groups represent external users and can be in the same or a different directory provider.
The second layer are the groups provided by that directory. In each directory, you want one group that defines all of the users who have access to Jira. Everyone who accesses Jira needs to be a member of jira_users. I want to identify users who are internal or external explicitly to delegate permissions. On the internal side, I’ve created a group called mars_users, and on the external side, it’s called all_partners. Both mars_users and all_partners will be added to the group jira-users.
I then have created a simple pattern for each of the external companies that need to access my Jira instance. Employees from the partner companies are users inside of the leaf groups. For example, user@externalcompany1.com is a member of group ext-company1. I recommend using email address as the username since it is universally identifiable.
.Step 2: Build your perfect project
Jira is customizable in so many ways: fields, screens, workflows, and more. If you have not built a Jira project before, I recommend building out your fields, screens, and workflows before proceeding. Have the internal team use the project for a while. Doing so will allow everyone on the internal team understand and provide feedback on the project setup. You’ll likely need to make a few changes based on feedback.
Once the base infrastructure is built, we can then add permissions and make it work for external users.
Step 3: Define Roles
Roles are one of the more flexible features inside of Jira. How do roles differ from groups? Groups are static set of people. Roles are flexible definitions of job functions.
Think about all of the job functions inside of your project. You might have things like: internal developer, project lead, and external partner lead. I’ve drafted a simple workflow that outlines how a company might outsource development to an external company.
What’s great about using roles is that we can separate the person from the job function. For example, when moving an issue out of internal review, the workflow will assign the issue to an external lead. If we embed the name or group of the external partner in the workflow, that workflow will only work for that one company. Using roles will allow us to flexibly use the workflow across multiple projects, parametrizing the people involved.
Step 4: Engage external users
Now you have a flexible set of roles and groups in the well-defined Jira project, let’s take a look at involving external parties.
Enable access to Jira
All people who access Jira need to be a member of the built-in group, jira-users. Add the top-level all_partners group and mars_users group to jira-users. This gives all of the external users access into Jira. Keep in mind, internal as well as external users require a license for Jira.
Give out permissions
When giving permission to a resource in Jira, I would use the following two questions to decide how I give permission:
- Do the people or groups change between Jira projects? – Use a role
- Is the same person or set of people consistent across all interactions in Jira? – Use a group
Jira controls permissions through three basic entities: permission schemes, issue security schemes, and workflows.
Permission Schemes
Permission schemes are the security backbone of your project. They control who can see the project and manipulate the core functions inside of that project. I’d like to draw your attention to the browse projects permission. This controls who can see that project inside of Jira. Let’s start by granting access to the group mars_users (internal employees) and the role partners (partners for that project).
In the configuration for the Company 1 project, we can grant access for Company 1 users by adding ext-company1 to the role partners for that project. We can do the same for project Company 2. Giving mars_users the browse projects permission allows all internal employees to see all projects. External users can only see Jira projects where their company group is added to the role partners.
Since every organization works differently, I would browse the different permission schemes and grant access conservatively. If someone needs access to something, you’ll definitely hear about it!
Issue Security Schemes
Teams that need to restrict visibility of issues within a project can do so with an issue security scheme. Issue security schemes control who can view a particular issue or its comments. This allows internal users to create issues or conversations in comments that external partners cannot see. Let’s create a new issue security scheme that restricts visibility of an issue to a set of people.
We can then associate this issue security scheme with our project. By default, issues will be visible by everyone. To make issues restricted by default, press the default link on the appropriate security level.
Securing Conversation
Jira secures conversations through roles. Let’s take a look at an example of a comment designed for the internal team.
How did I do this? I created a role called Internal Employees. Since this role doesn’t change per project, I can set the default member to be mars_users.
If you have existing projects, you’ll want ensure that the new role has users or groups populated. If the role does not have any members, it will not show up in the list of options to secure comments.
Workflow transitions
Through the use of conditions and post functions, Jira administrators can control how users move issues through a workflow. Let’s take a look at an example of each.
Conditions: For instance, many teams want internal employees to sign off on changes made by external parties. Use a condition that requires the user to be a member of internal employees.
Post Functions: Post functions make it easy to route issues to the right team or user in the workflow. Using the Jira Misc Workflow Extensions plugin, it’s easy to assign issues between organizations using a workflow transition. In the below example, we are routing the issue to the last partner user who was assigned the issue:
Step 5: Stage, test, deliver
One of the best things you can do is create a staging instance of Jira. Having a staging instance allows administrators to test changes to ensure there are no unintended side effects. You should also create a flexible set of test artifacts. At a minimum I suggest:
- A test internal employee user
- A test external partner user
- A test external partner group
These three entities will allow you to fully test workflows without sending bogus emails to ask people.
Take your testing and delivery to the next level!
For administrators who want to streamline the creation and management of projects, I highly recommend the Jira Command Line Interface. Administrators can then script the creation of projects to make deployments easier and more predictable. How would we do this?
jira --action createProject --project "ACME" --name "Acme Partnership"
--description "TIS and Acme partnership" --lead "you@teamsinspace.com"
--issueSecurityScheme "Partner Security Scheme"
--permissionScheme "Partner Permission Scheme"
There are also options to populate users, roles, workflows, fields, and many other Jira options.
Jira’s Rest API allows administrators for developers to create automated tests to ensure permissions are set up correctly. I’d start small and validate very simple use cases to ensure data security. Things to do?
- Login as an external user and ensure you cannot view an issue intended for an internal employee
- Check to see that transitions for internal employees are not available
- Validate that Partner 2 cannot see projects intended for Partner 1
A few last tips:
- When designing your instance, ensure that you are as secure as possible. Consider making most the restrictive options for internal employees so they have to choose to share with external partners.
- When rolling out new changes that affect how security options work, use an announcement banner to notify users of the change. HTML is supported, so it’s easy to link to another document.
- Educate users about how to name and distribute shared objects, like agile boards and filters, so that your system remains air-tight and does not leak secure information.