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.” jira_directory_setup

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.

ProTip: Don’t call the access group for internal employees “internal employees”. When you need to remove someone from that group, the request “remove jsmith from internal_employees” can have multiple meanings (smile).

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.

jira_roles_worflows

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

jira_browse_permission

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!

ProTip: Consider modifying the default permission scheme rather than creating a new one. Doing so will ensure that all new projects have the desired security settings.

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.

jira_issue_security_schemes

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.

jira_restrict_comments

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.

jira_default_roles

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.

jira_workflow_condition

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:

jira_post_function

ProTip: Post functions can also change the security level for an issue. If your workflow has a review phase, a post function can change external partner visibility inside of a transition.

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?

1
2
3
4
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.

Does your team have a setup like this running? Let us know! We are always curious to hear how our customers configure and deploy JIRA.

About Dan Radigan

Software has been a passion since the days of the floppy disk (you know, the actual 5.25 inch floppy ones). Agile has had a huge impact on me both professionally and personally as I've learned the best experiences are agile, both in code and in life. You'll often find me at the intersection of technology, photography, and motorcycling. Find me on twitter @danradigan.

View all posts by Dan Radigan »