In the previous chapters, you learned how to store data in JIRA by creating issues. As you can see, as an information system, JIRA, is all about data. It should come as no surprise to you that security plays a big role in JIRA, not only to ensure that the right people will get access to our data, but also to maintain data integrity by preventing accidental changes.
By the end of this chapter, you will have learned the following:
- User directories and how to connect JIRA to LDAP
- General access control in JIRA
- Managing fine-grained permission settings
- How to troubleshoot permission problems
Before we delve into the deep end of how JIRA handles security, let's first take a look at how JIRA maintains user and group memberships.
User directories are what JIRA uses to store information about users and groups. A user directory is backed by a user repository system, such as LDAP, a database, or a remote user management system, such as Atlassian Crowd.
You can have multiple user directories in JIRA. This allows you to connect your JIRA instance to multiple user repositories. For example, you can have an LDAP directory for your internal users and a database directory (a JIRA internal directory) for external users. An example is given in the following screenshot, where we have two user directories configured. The first user directory is the built-in JIRA Internal directory running on the JIRA database. The second user directory is connected to the Microsoft Active Directory (Read Only) in the read-only mode. The last user directory is connected to the crowd, a user identity management software from Atlassian:
As a JIRA administrator, you can manage user directories by performing these two steps:
- Browse to the JIRA administration console.
- Select the User management tab and then the User Directories option.
From here, you can see the list of user directories you currently have configured in JIRA, add new directories, and manually synchronize with the remote user repository.
When adding a new user directory, you need to first decide on the directory type. There are several different user directory types within JIRA:
- JIRA internal directory: This is the built-in default user directory when you first install JIRA. With this directory, all the user and group information is stored in the JIRA database.
- Active directory (AD)/LDAP: This is used when you want to connect JIRA to an LDAP server. With this directory, JIRA will use the backend LDAP to query user information and group membership. This is also known as an LDAP connector and should not be confused with internal and LDAP authentication directories.
- Internal with LDAP authentication: This is also known as a Delegated LDAP. With this directory type, JIRA will only use LDAP for authentication and will keep all user information internally in the database (retrieved from LDAP when the user successfully authenticates for the first time). This approach can give a better performance. Since LDAP is only used for authentication, this avoids the need to download larger numbers of groups from LDAP.
- Atlassian Crowd: If you are also using Atlassian Crowd, a user management and Single Sign-On (SSO) solution, you can use this directory type to connect to your crowd instance. With this option, you can also configure your JIRA instance to participate in the SSO session.
- Atlassian JIRA: JIRA is capable of acting as a user repository for other compatible applications. If you have another JIRA instance running, you can use this directory type to connect to the other JIRA instance and for user information.
When you have multiple user directories configured for JIRA, there are a few important points to keep in mind. The order of the user directories is important, as it will directly affect the order JIRA will use to search users and apply changes made to users and groups. For example, if you have two user directories and both have a user called admin with different passwords, this will have the following effects:
- When you log in to JIRA with the user admin, you will be logged in as the admin user from the first user directory that is able to validate the password, in the order of listed directories.
- After logging in, you will be granted group membership from the directory that has validated your password. Any other directories will be skipped.
- If you make a change to the admin user, such as changing the full name, then the changes will only be applied to the first directory JIRA has write access to.
Another important point to remember when working with user directories is that you cannot make changes to the user directory when you are logged in with a user account that belongs to the said directory. For example, if you are logged in with an LDAP account, then you will not be able to make changes to JIRA's LDAP settings, since there is a potential for the new change to actually lock you out of JIRA.
Tip
Always have an active administrator user account ready in the default JIRA internal directory; for example, the account created during the initial setup. This will provide you with an administrator account that can help you fix user directory problems such as the preceding scenario. If you have a user account with the same name in the other user directory, then the internal directory should also be the first one in the list.
JIRA supports a wide range of LDAP servers including Microsoft Active Directory, OpenLDAP, and Novell eDirectory server. If a particular LDAP is not listed as one of the options, then we also have a Generic Directory Server option.
When using the AD/LDAP connector directory type, you can choose to connect with one of the permission options:
- Read only: JIRA cannot make any modifications to the LDAP server.
- Read only, with local groups: Information retrieved from LDAP will be read-only, but you can also add users to groups created within JIRA. These changes will not be reflected in LDAP.
- Read/Write: JIRA will be able to retrieve and make changes to the LDAP server.
The Read only option is the most common option, as the IT team often centrally manages LDAP servers and changes are not allowed. With this option, JIRA will only use data stored in LDAP to verify user credentials and group membership. If you only want to use LDAP as a user repository and authentication, but still want to have the flexibility to update group membership without having to get the LDAP team involved, then the Read only, with local groups option will be the best fit. Lastly, the Read/Write option should be avoided, as propagating changes to LDAP, such as group membership, can have an unforeseen impact on other systems also relying on the same LDAP server.
To connect your JIRA to LDAP, all you have to do is add a new user directory:
- Browse to the User Directories page.
- Click on the Add Directory button and select either Microsoft Active Directory or LDAP from the Directory Type select list, and then click on Next.
- Provide your LDAP server information.
Since every LDAP is different, the exact parameters that are required will vary. At a minimum, you need to provide the following information:
|
Parameter |
Description |
|
Name |
This is the name of the user directory. |
|
Directory Type |
This is where you select the flavor of your LDAP. This will help JIRA to prefill some of the parameters for you. |
|
Hostname |
This is the hostname of your LDAP server. |
|
Port |
This is the port number of your LDAP server. JIRA will prefill this based on your directory type selection. |
|
Base DN |
This is the root node for JIRA to search for users and groups. |
|
LDAP Permissions |
This helps choose whether JIRA should be able to make changes to LDAP. |
|
Username |
This is the username that JIRA will use to connect to LDAP for user and group information. |
|
Password |
This is the password that JIRA will use to connect to LDAP. |
You can see these sections completed in the following screenshot:
Apart from the preceding parameters, there are additional advanced settings such as User Schema Settings and Group Schema Settings. After filling in the form, you can click on the Quick Test button to verify that JIRA is able to connect to your LDAP server and authenticate with the username and password provided. Note that this does not test for things such as the user lookup. If the initial quick test is successful, then you can go ahead and click on the Save and Test button. This will add the user directory and take you to the test page where you can test the settings with a proper user credential (this will be different than the one used by JIRA to connect to LDAP):
After the new user directory is added, JIRA will automatically synchronize with the LDAP server and pull in users and groups. Depending on the size of your LDAP server, this may take some time to complete. After the initial synchronization, JIRA will periodically synchronize with LDAP for any changes.