Documentation for Crowd 2.3. Documentation for other versions of Crowd is available too.

Skip to end of metadata
Go to start of metadata
Crowd 101

Thank you for choosing Crowd. To help you get up and running quickly, we have compiled some quick-start instructions on configuring and using Crowd with your JIRA and Confluence applications.

(info) This quick-start guide assumes that you have installed and set up JIRA and/or Confluence and now wish to set up Crowd for user management in one or both of them.

  • If you want to use JIRA or Confluence but have not yet installed them, please follow the instructions in JIRA 101 and/or Confluence 101 before configuring Crowd.
  • If you want to use Crowd with other applications but not JIRA or Confluence, please follow the detailed Crowd installation and setup guide rather than this 'Crowd 101' guide.

Getting Started

1. Installing Crowd

First things first. If you have not already got Crowd up and running, carry out the following steps:

  For Windows: (click to expand)
  1. Go to the Atlassian download centre.
  2. Download the ZIP archive file for the Crowd distribution (not EAR-WAR).
  3. Unzip the zip archive into a directory of your choice, avoiding spaces in the directory name.
  4. Tell Crowd where to find its Crowd Home directory, by editing the crowd-init.properties file as described in the installation guide.
  5. Set up your database as described in the database configuration guide.
    (info) This quick-start page assumes that you have an existing JIRA or Confluence application. So we recommend that you connect Crowd to a production-ready database and not HSQLDB. But if you are evaluating Crowd, it is fine to use HSQLDB and then move to a different database later. In that case, you do not need to do anything in this step, because Crowd contains everything you need.
  6. Start your Crowd server by going to the directory where you unzipped Crowd and running start_crowd.bat.
  7. To access Crowd, go to your web browser and type this address: http://localhost:8095/crowd.
  8. Follow the Setup Wizard. This will guide you through the process of setting up your Crowd server and creating an admin user.

For more help on the technical procedures in this section, please refer to the Crowd installation guide.

If you need assistance, please create a support ticket.

  For Mac: (click to expand)
  1. Go to the Atlassian download centre.
  2. Click the 'Mac OS X' tab and download the TAR.GZ archive file for the Crowd distribution (not EAR-WAR).
  3. Unzip the archive into a directory of your choice, avoiding spaces in the directory name.
  4. Tell Crowd where to find its Crowd Home directory, by editing the crowd-init.properties file as described in the installation guide.
  5. Set up your database as described in the database configuration guide.
    (info) This quick-start page assumes that you have an existing JIRA or Confluence application. So we recommend that you connect Crowd to a production-ready database and not HSQLDB. But if you are evaluating Crowd, it is fine to use HSQLDB and then move to a different database later. In that case, you do not need to do anything in this step, because Crowd contains everything you need.
  6. Start your Crowd server by going to the directory where you unzipped Crowd and double-clicking start_crowd.sh.
  7. To access Crowd, go to your web browser and type this address: http://localhost:8095/crowd.
  8. Follow the Setup Wizard. This will guide you through the process of setting up your Crowd server and creating an admin user.

For more help on the technical procedures in this section, please refer to the Crowd installation guide.

If you need assistance, please create a support ticket.

  For UNIX or Linux: (click to expand)
  1. Go to the Atlassian download centre.
  2. Click the 'Linux' tab and download the TAR.GZ Archive file for the Crowd distribution (not EAR-WAR).
  3. Unzip the archive into a directory of your choice, avoiding spaces in the directory name.
  4. Tell Crowd where to find its Crowd Home directory, by editing the crowd-init.properties file as described in the installation guide.
  5. Set up your database as described in the database configuration guide.
    (info) This quick-start page assumes that you have an existing JIRA or Confluence application. So we recommend that you connect Crowd to a production-ready database and not HSQLDB. But if you are evaluating Crowd, it is fine to use HSQLDB and then move to a different database later. In that case, you do not need to do anything in this step, because Crowd contains everything you need.
  6. Start your Crowd server by going to the directory where you unzipped Crowd and double-clicking start_crowd.sh.
  7. To access Crowd, go to your web browser and type this address: http://localhost:8095/crowd.
  8. Follow the Setup Wizard. This will guide you through the process of setting up your Crowd server and creating an admin user.

For more help on the technical procedures in this section, please refer to the Crowd installation guide.

If you need assistance, please create a support ticket.

2. Adding Users and Groups

Crowd is designed to help you manage users and groups across multiple applications. Your next step is to configure a user directory in Crowd to contain your JIRA and/or Confluence users and groups.

  If you are starting out from scratch with a new JIRA and a new Confluence site: (click to expand)
  1. Add a Crowd directory — Add a Crowd Internal directory to contain all your JIRA and Confluence users.
  2. Add the Confluence groups — Add the 'confluence-users' and 'confluence-administrators' groups to your new directory.
  3. Add the JIRA groups — Add the 'jira-users', 'jira-developers' and 'jira-administrators' groups to your new directory.
  4. Import your users from a CSV file or add them manually.
  5. Add the users to the groups — Use Crowd's bulk user management to add all the users to the 'confluence-users' and 'jira-users' groups. Also add any administrators to the administration groups and add the developers to the 'jira-developers' group. For more details about the permissions applicable to each group, refer to the Confluence and JIRA documentation.
  If you have existing JIRA and Confluence sites, each currently managing its own set of users internally: (click to expand)

If your JIRA users are currently managed via JIRA's internal management and your Confluence users are managed separately via Confluence's internal management, you can use Crowd to simplify and centralise your user and group management:

  1. Add a Crowd directory — Use the Crowd Administration Console to add a Crowd Internal directory to contain all your JIRA and Confluence users.
  2. Import the users and groups from Confluence — Use the Crowd importer to copy your users and groups from Confluence into the new Crowd directory. This process will also copy the group memberships into Crowd.
  3. Import the users and groups from JIRA — Use the Crowd importer to copy your users and groups from JIRA into the same Crowd directory as the Confluence users. This process will add any additional users and groups from JIRA and update the existing Confluence users with their JIRA group memberships.
  4. Check your users and groups in Crowd — Use Crowd's group browser to check that your users, groups and group memberships are available as expected in Crowd.
  If you have existing JIRA and Confluence sites, with all users currently managed internally in JIRA: (click to expand)

If your JIRA and Confluence users are currently all managed via JIRA's internal management, you can use Crowd to simplify and centralise your user and group management:

  1. Add a Crowd directory — Use the Crowd Administration Console to add a Crowd Internal directory to contain all your JIRA and Confluence users.
  2. Import the users and groups from JIRA — Use the Crowd importer to copy your users and groups from JIRA into the new Crowd directory. This process will also copy the group memberships into Crowd.
  3. Check your users and groups in Crowd — Use Crowd's group browser to check that your users, groups and group memberships are available as expected in Crowd.
  If you have existing JIRA and Confluence sites, with all users currently managed in an LDAP directory: (click to expand)

If your users are in a corporate LDAP directory, you can choose whether you want to store your groups in LDAP or in Crowd.

  If none of the above scenarios matches your requirements: (click to expand)

Take the following steps, choosing your directory and other options as indicated in the linked documentation:

  1. Add a Crowd directory — Choose the directory type you need to contain all your JIRA and Confluence users.
  2. Add your users and groups either via Crowd's importer or manually:
    • Import your users and groups into Crowd.
    • Or do it manually:
      1. Add the users.
      2. Add the Confluence groups — Add the 'confluence-users' and 'confluence-administrators' groups to your new directory.
      3. Add the JIRA groups — Add the 'jira-users', 'jira-developers' and 'jira-administrators' groups to your new directory.
      4. Add the users to the groups — Use Crowd's bulk user management to add all the users to the 'confluence-users' and 'jira-users' groups. Also add any administrators to the administration groups and add the developers to the 'jira-developers' group. For more details about the permissions applicable to each group, refer to the Confluence and JIRA documentation.

(info) If you have Confluence or JIRA, but not both, pick the scenario above that best matches your requirements, then just skip the steps for the application that you do not need.

3. Connecting the Applications

Crowd manages your users' access to your applications and makes single sign-on (SSO) possible. (More about SSO below.) For this to happen, you need to tell Crowd about the applications and to copy some Crowd libraries into the applications' installation folders.

  1. Add Confluence — Add the Confluence application to Crowd, following the instructions in the Add Application Wizard.
    • Choose 'Confluence' as the application type.
    • In the 'Directories' step, choose the user directory you added for Confluence.
    • In the 'Authorisation' step, allow all users to authenticate.
  2. Configure the Crowd libraries in Confluence — Copy the Crowd client libraries into your Confluence folders and configure the properties files as described on the Confluence integration page.
  3. Now add JIRA — Add the JIRA application to Crowd, following the instructions in the Add Application Wizard.
    • Choose 'JIRA' as the application type.
    • In the 'Directories' step, choose the user directory you added for JIRA.
    • In the 'Authorisation' step, allow all users to authenticate.
  4. Configure the Crowd libraries in JIRA — Copy the Crowd client libraries into your JIRA folders and configure the properties files as described on the JIRA integration page.

(info) We will call these your 'Crowd-connected applications'.

Mastering the Basics

4. Examining your Crowd Server Setup

Go to the System Information screen in Crowd's Administration Console to find useful information about your Crowd server, such as the location of your Crowd Home directory, information about your database and JVM, and your license server ID.

5. Managing SSO

If you have configured single sign-on (SSO) when setting up your Crowd-connected applications (JIRA and Confluence) in step 3 above, your users will only need to log in or log out once, to Crowd or any Crowd-connected application. When they start another Crowd-connected application, they will be logged in automatically. Similarly, when they log out of Crowd or one of the Crowd-connected applications, they will be logged out of Crowd and the other application(s) at the same time.

  • Overview of SSO — An overview of Crowd's SSO capabilities, plus links to detailed information.
  • Configuring Trusted Proxy Servers — If you are running applications behind one or more proxy servers, you may find it useful to configure Crowd to trust the proxies' IP addresses.

Managing your Users' Experience of Crowd

(info) Your users will need to access Crowd at http://<Crowd machine name>:8095/crowd (not http://localhost:8095/crowd).

6. Testing a User's Login

  Why would I do this? (click to expand)

You may want to test a user's login to a specific application if the user has reported problems with logging in, or if you have just set up the first user to access a new application. The test verifies whether a user will be able to log in to a given application, based on the application, directory and group associations in Crowd.

  How do I do this? (click to expand)

Go to the application's 'Authentication Test' tab in the Crowd Administration Console, as described in the documentation. The documentation also describes the possible error messages and the steps you can take to resolve any problems.

7. Changing or Resetting a User's Password

  Why would I do this? (click to expand)

You may need to change or reset someone's password, if they have forgotten their password or if someone else has come to know the password.

(info) Crowd users can change or reset their own passwords too. See the user documentation. To allow this, you need to grant them Crowd user rights, as described below.

  How do I do this? (click to expand)

Go to the 'User Details' screen in the Crowd Administration Console, as described in the documentation.

If you have configured an email server and a notification template, Crowd will send the user an email about their new password.

8. Setting Up User Aliases

  Why would I do this? (click to expand)

Aliases are useful if the same person has different usernames in JIRA and Confluence. You can define the user just once in Crowd, and allocate one or more aliases for the different applications that the user can access.

  How do I do this? (click to expand)

The documentation has the full details. In summary:

  1. Make sure that aliasing is enabled for JIRA and Confluence, on the application's 'Options' screen.
  2. Add the appropriate alias for each user, on the user's 'Applications' screen.

9. Granting Crowd User Rights to Someone

  Why would I do this? (click to expand)

You can give your users access to Crowd's Self-Service Console, where they can edit their own profile, change their password and see the applications they are allowed to access. They can read the Crowd User Guide for guidance.

  How do I do this? (click to expand)

Make sure that the person's username is in a user directory where all users are authorised to use Crowd. Please refer to the documentation for details.

10. Granting Crowd Administrator Rights to Someone

  Why would I do this? (click to expand)

When you first set up Crowd, you will define a single Crowd administrator. It is advisable to give other people administration rights too, so that you do not run into problems when the single administrator is unavailable.

  How do I do this? (click to expand)

Make sure that the person is a member of the 'crowd-administrators' group. Please refer to the documentation.

Important Next Steps

11. Setting Up your Applications' Host Names

When you set up your applications in step 3 above, you will have specified an IP address for each application. If JIRA, Confluence or any Crowd-connected application resides on a server that passes Crowd a host name instead of an IP address, you will need to tell Crowd the host name. Please refer to the documentation.

12. Connecting to an External Database

If you decided to use the default HSQLDB database when you set up Crowd, you need to switch to a production-ready database before using Crowd as a production system. HSQLDB is provided for evaluation purposes only. Please refer to the documentation.

13. Backing Up your Crowd Data

To back up your Crowd data and establish processes for regular backups, please refer to the documentation.

Thank you for choosing Crowd.

We are always happy to help. Feel free to email or call us with any questions you may have.