In the previous chapters, you have learned how to store data in JIRA by creating issues. As you can see, as an information system, JIRA is all about data. So, it should come as no surprise to you that security plays a big role in JIRA to not only ensure only the right people will get access to our data, but also maintain data integrity by preventing accidental changes.
Starting with JIRA 4.4, there have been many significant improvements in the user management area, including simplifying the LDAP integration and adding the ability to have multiple user repositories with the user directory feature. JIRA 5 has continued on this path and kept on improving these features.
By the end of the 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 to multiple user repositories. For example, you can have an LDAP directory for your internal users and a database directory (for example, JIRA internal directory) for external users. For example, in the following screenshot, we have two user directories configured. The first user directory is connected to Microsoft Active Directory (Read Only), while the second one is a built-in JIRA Internal directory running on a database:
Perform the following steps to access the user directories interface:
- Browse to the JIRA administration console.
- Select User Directories from the Users section.
While 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/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 LDAP Connector, and should not be confused with Internal and LDAP Authentication directories.
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 there is also 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.
- Internal with LDAP authentication: Also known as Delegated LDAP, with this directory type, JIRA will only use LDAP for authentication, and will keep all user information internally in the database. This approach can have 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 SSO solution), you can use this directory type to connect to your Crowd instance. With this option, you can also configure your JIRA 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 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, 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 with 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 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 where the new change may actually lock you out of JIRA.
In the days prior to user directories, connecting to LDAP was a tedious process of manually editing configuration files and restarting the system. With user directories, it is much easier to connect JIRA to an LDAP server for user management.
To connect your JIRA to LDAP, all you have to do is to add a new user directory:
- Browse to the User Directories page.
- Click on on the Add Directory button and select the either Microsoft Active Directory or LDAP.
- 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 |
|---|---|
|
This is the name of the user directory. | |
|
Select the flavor of your LDAP. This will help JIRA to prefill some of the parameters for you. | |
|
This is the hostname of your LDAP server. | |
|
This is the port number of your LDAP server. JIRA will prefill this based on your directory type selection. | |
|
This is the root node for JIRA to search for users and groups. | |
|
This helps choose whether JIRA should be able to make changes to LDAP. | |
|
This is the username JIRA should use to connect to LDAP for user and group information. | |
|
This is the password for JIRA to use to connect to LDAP. |
You can see these sections filled in the following screenshot:
Apart from the preceding parameters are additional advanced settings such as User configuration and Group schema configuration. After filling in the form, you can click on on the Quick Test button to verify if 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 look up. 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 should 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 upon the size of your LDAP, this may take some time to complete. After the initial synchronization, JIRA will periodically synchronize with LDAP for any changes.