Overview

One of the areas that a new JIRA administrator commonly feels uncertain about is adding, modifying, and deactivating users in JIRA. This chapter covers some of the different aspects of the lifecycle of a JIRA user.

Adding Users

Before someone can log into JIRA, a JIRA administrator has to create a user account for them. A JIRA administrator is someone in the jira-administrators or jira-system-administrators groups,¹ not someone in the project role Administrators.

As one might expect, JIRA has an internal user directory of user accounts, but there are also a number of other ways to define JIRA users.

When you add new users to JIRA you can just look an existing user’s groups and take those as a template for what the new user needs. However this can soon become confusing. A better idea is to have the expected use of JIRA groups and project roles documented somewhere for each JIRA project. It’s an odd quirk that JIRA groups don’t have a description associated with them, and cannot be easily renamed.

The most common request is to have JIRA work with user accounts that have already been defined for other applications and network domains. For example, many organizations have a Microsoft Active Directory (AD) server where users and groups are defined. Such groups may even contain email aliases that users can modify themselves. JIRA can use such directory services in a number of different ways:

Authentication

The passwords for JIRA users are the same as their passwords in the external directory service. This is usually the easiest one to set up.

Authorization

The different groups that JIRA users belong to are defined in the directory service. This often means that changes to group membership have to be performed by the directory service administrators.

Provisioning of User Accounts

The user accounts in JIRA are automatically created when they appear in the directory service. Automatic deactivation of accounts requires that the groups are also defined in the directory service.

Atlassian has a directory service product named Crowd that integrates with JIRA and all the other Atlassian products such as Confluence, FishEye/Crucible and Bamboo. This allows you to manage all your Atlassian users and their groups in one place. Crowd can synchronize its list of users from another directory service such as AD or Google Apps.

However, as of JIRA 4.3, much of the user management aspect of Crowd was merged into JIRA, where a user directory can be defined for each external directory service. Crowd is still required for single sign-on (SSO) or possibly large numbers of users. However I have used JIRA alone with 15,000 users directly with no problems.

For more detailed information about the different ways to add users to JIRA and user directories, please see the documentation at http://confluence.atlassian.com/display/JIRA/Managing+Users and http://confluence.atlassian.com/display/JIRA/Configuring+User+Directories.

Adding Third-Party Users

A common requirement is to give a group of third-party users, such as contractors, access to only some of JIRA. One way to do that is as follows:

1. Create a new JIRA group named something like third-party-users. Add the third-party users to this group, but do not add them to the default jira-users group that all your staff are in.

2. At the Global permissions page (Administration→System→Global permissions), grant the JIRA Users permission to the new third-party-users group. This will allow the members of that group to log into JIRA.

3. Now go to each JIRA project where you want the third-party users to be able to view or edit issues. Add the new third-party-users group to the appropriate project roles. This is usually the Users or Developers role, but depends on the local permission scheme used by the project.

JIRA restricts who can see user names and email addresses according to the groups that have the global permission Browse Users. However, there are a few obscure ways in which this data can leak out.

Modifying Users

The only constant is change, so you should expect JIRA user accounts to need updating. If a user is defined in the JIRA internal user directory, then changing a user’s email address and full name is easy enough to do: go to Administration→User Management→Users, find the user, and click Edit. If the user is defined in an external LDAP directory (such as Active Directory), you most likely can’t change these details from within JIRA. The Directory Configuration Summary link at Administration→User Management→User Directories shows the allowed operations for each user directory. Note that very few AD instances ever allow the applications that use them to change data in AD.

JIRA requires that all users created in the JIRA internal user directory have an email address. However users from external user directories can be created without email addresses. This can cause occasional errors to be seen in log files but doesn’t seem to have any other effects.

JIRA doesn’t check for duplicate email addresses for its users, so you can create two users with the same email address. However, both JIRA users may be sent email from within JIRA, which will result in receiving duplicate emails at the same email address. This is confusing, so avoid using duplicate email addresses when possible. Also, if an email message is used to create a comment on an issue (see the section “Email”), JIRA assumes that the comment was sent by the first user whose email address matches the From address in the email.

As an aside, a user’s full name can also be used to contain information about their affiliation (e.g., John Smith [Example Company]). The full name can be up to 255 characters.

Deactivating Users

When a user should no longer have access to JIRA, they can be deactivated. This is preferable to deleting them, which removes useful historical information (and is also more work in older versions of JIRA). The term is also less ambiguous than disabling someone. A deactivated user cannot log in and also does not appear in lists of users (e.g., for assigning issues).

The steps to deactivate a user are simple:

1. Go to Administration→User Management→Users.

2. Find the user, and click Edit.

3. Uncheck the Active checkbox and click Update.

The user will no longer appear be able to log in to JIRA even though they are not removed from the jira-users group. The user does not count towards the licensed user count. Their name will have (Inactive) appended, and they will not receive email (except for Subscriptions). However, any issues currently assigned to the user will still be assigned to the same inactive user. A bulk change can be used to reassign those issues to an active user. More details can be found at http://bit.ly/11CYl4W.

Handling deactivated users in external directory services is more involved. Such users are commonly marked as inactive in AD and then periodically moved to an inactive area by an IT team. If the user is actually deleted from AD, then the best approach is to create users in the JIRA internal user directory, and then deactivate the user as usual. This will preserve the history of the user in JIRA issues. Otherwise JIRA will display Anonymous instead of the userid in earlier versions of JIRA. In more recent versions the userid will be displayed, but not as a link. Editing issues with non-existent users can cause errors if the reporter is required.

Monitoring Users

An often overlooked feature in JIRA is the ability to see which users are logged in by using Administration→System→User sessions. This feature can be useful during upgrades (see Chapter 8) for checking who needs to log out before the upgrade can begin. You can also send email to such users from within JIRA at Administration→System→Send mail.

If the JIRA users are defined in an external directory service, then it’s often helpful to disable the CAPTCHA password protection (navigate to Administration→System→Settings, and clear the Maximum Authentication Attempts Allowed value). This is because if a user has locked themselves out of an Active Directory server with multiple failed password attempts, then entering a correct CAPTCHA will never unlock their password, and so just causes confusion. CAPTCHAs work best when all the users are in the JIRA internal user directory.