Importing user from LDAP

All Versions

JIRA 4.0 Beta Documentation

Index

JIRA's LDAP integration currently requires users to have accounts both in LDAP and in JIRA. For instance, if a user is added to LDAP, they will have no access to JIRA until someone creates them a JIRA username (and assigns it to groups).

The attached tool searches LDAP for user accounts, and generates a JIRA Jelly script which will create a JIRA user account for each LDAP account. Typically one would use this tool when first installing JIRA, to bulk-create JIRA users matching each LDAP account.

How to use

Download the current binary distribution. Alternatively, if you are Java-literate and keen, all current distributions contains source distributions. You can also get the source from Subversion at http://svn.atlassian.com/svn/public/contrib/jira/jira-ldap-userimporter/trunk.

Create a file, ldap.properties, to specify your LDAP server's details. If you are unsure of these, first test with an LDAP browser (there are many LDAP browsers available on the internet, you can try using this LDAP browser or search for an alternative one). Here is a ldap.properties configured for use against a local OpenLDAP directory:

# Configuration file for JIRA's LDAP user importer

# URL of your LDAP server, Eg:
java.naming.provider.url=ldap://192.168.0.74

# Username and password of account that has privileges to loop through all users, eg:
java.naming.security.principal=cn=admin,dc=atlassian,dc=com
java.naming.security.credentials=secret

# LDAP node below which we should search, eg:
searchbase=ou=People,dc=atlassian,dc=com

# LDAP query run below 'searchbase' identifying user nodes, eg:
query=(objectclass=*)

# Name of record in nodes which should become the username in JIRA, eg:
username_attr=uid

# Record that contains the user's full name. When commented out, defaults to username_attr value. Eg:
fullname_attr=cn

# Record that specifies the user's email address. When commented out, username_attr value with email_suffix appended will be used
#email_attr=
email_suffix=@atlassian.com


# Generally you don't want to touch this
java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory

Once you have created ldap.properties, run java -jar jira-ldap-userimporter-1.1.jar. If you have the ldap.properties details correct, this command will result in XML text being printed to the console. Eg:

~/jira-ldap-userimporter-1.1$ java -jar jira-ldap-userimporter-1.1.jar
<JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraTagLib">
  <jira:CreateUser username="nobody" password="nobody" confirm="nobody" fullname="nobody" email="nobody@atlassian.com"/>
  <jira:CreateUser username="jturner" password="jturner" confirm="jturner" fullname="Jeff Turner" email="jturner@atlassian.com"/>
  <jira:CreateUser username="anonymous" password="anonymous" confirm="anonymous" fullname="anonymous" email="anonymous@atlassian.com"/>
  <jira:CreateUser username="devuser" password="devuser" confirm="devuser" fullname="devuser" email="devuser@atlassian.com"/>
</JiraJelly>

This text can now be redirected to a file, and fed to the Jelly Runner (see the Jelly docs).
However, first make sure that LDAP password checking is disabled (ie. there is no LDAPCredentialsProvider section in osuser.xml), otherwise the Jelly script will fail, claiming these users already exist.

Feedback? Problem

Please raise a Support Request.

Exceeding your user limit on import?
If you are getting a LimitExceededException, you may find these instructions from one of our customers helpful.
Thanks to Ricardo Sueiras

Version History

Version Comments
1.1 Username is converted to lowercase automatically
1.0 First Released
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Comments (11)

 

  1. Dec 05, 2006

    Zhang Mingquan Mike says:

    It takes me a long time to get the configuration work correctly. #java.nami...

    It takes me a long time to get the configuration work correctly.

    #java.naming.security.principal=cn=admin,dc=atlassian,dc=com

    For exchange server, user@domain works for principal.

  2. Jan 31, 2007

    Peter Brandström says:

    It seems oscore-2.2.6-dev-9Nov05.jar works, but oscore-2.2.5.jar does not. ...

    It seems oscore-2.2.6-dev-9Nov05.jar works, but oscore-2.2.5.jar does not. Very annoying.

    It's incomprehensible to me, but I'm not a Java developer.

  3. Apr 12, 2007

    Matt Stevens says:

    oscore-2.2.6-dev-9Nov05.jar works on over 20 thousand LDAP users the xml genera...

    oscore-2.2.6-dev-9Nov05.jar works

    on over 20 thousand LDAP users the xml generation ran just fine

    however, with a nested addUsertoGroup element on each entry on standalone 3.8 with HSQL I got at best 300 users per minute and it degraded from there.  not surprising that buffers thrashed

    I only recommend loading maybe 1000 users at time 

  4. Jul 31, 2007

    Ben Jones says:

    When I run the jar to generate the Jelly XML script it processes about 100 users...

    When I run the jar to generate the Jelly XML script it processes about 100 users then I get the following error message

    Exception in thread "main" javax.naming.SizeLimitExceededException: [LDAP: error code 4 - Sizelimit Exceeded]; remaining
    name 'DC=news,DC=newslimited,DC=local'

    After a brief google search I found the following:

    "you are hitting a Size Limit set by the ldap server. to overcome this you can use pagedResultControl or Virtual List View to limit the numbers to get back from LDAP Server"

    I am not a LDAP guru by any means. Any suggestions on what exactly I need to do to fix this? Do I need to change the parameters on LDAP or do I need to change something in the ldap.properties file?

    1. Aug 13, 2007

      Jeremy Largman says:

      Ben, Please start a support issue (support.atlassian.com) if you're stuck. Here...

      Ben,

      Please start a support issue (support.atlassian.com) if you're stuck. Here's what we've found works to correct this:

      1. If you are able to, re-configure the LDAP server to increase the LIMIT allowed back. You need only do this while you are importing.

      2. In the userimporter properties file, reduce the size of the LDAP query. For example do the A users first, then the B users and so on. For example

      query=(objectclass=* and username=A*)

      I cant give you the exact query because it depends on the structure of your LDAP instance. You're looking for a search term that will find only a subset of the entries.

  5. Jan 21, 2008

    John Gallucci says:

    Ran into the problem with Exception in thread "Main". The problem was I install...

    Ran into the problem with Exception in thread "Main". The problem was I installed the non-development version of oscore*.jar. To fix it I downloaded the development package (at the time called oscore-2.2.6-dev-9Nov05.jar)

    Also, remember to use at the flag -cp . when running the java command and place oscore-2.2.6-dev*.jar in the same directory as jira-ldap-userimporter-1.x.jar. For java newbies (like myself) this allows the classpath to load at the command line using the same directory.

  6. Feb 18, 2008

    Peter Namuj says:

    I had some issues in the beginning with Exception in thread "Main", you would ne...

    I had some issues in the beginning with Exception in thread "Main", you would need to download and use oscore-2.2.6-dev-9Nov05.jar thats the only one that seems to work. Also something that the above directions doesn't tell you is that you can use both ldap:// or ldaps:// to be on the safe side specify the port as well (ldap://ldap_server:389 or ldaps://ldap_server:636).

  7. Nov 10, 2008

    John Price says:

    Thanks for this great utility. I was able to use it on Windows without any probl...

    Thanks for this great utility. I was able to use it on Windows without any problems (after I downloaded 7-Zip to deal with gz/tar files on Windows). A couple of comments:

    1) The ldap.properties file should be in the same directory as the .jar file. On Windows I ran this:

    -jar jira-ldap-userimporter-1.1.jar > jira-jelly-userimport.xml

    To create the Jelly file.

    2) R.e. this: "However, first make sure that LDAP password checking is disabled (ie. there is no LDAPCredentialsProvider section in osuser.xml), otherwise the Jelly script will fail, claiming these users already exist."

    You don't really have to do that if you've only created a couple of JIRA users manually. Instead you can just open the script file you create and delete any rows that correspond to existing users. You'll probably do this anyway so you can delete any weird non-human domain accounts you may have.

    Great stuff!

  8. Jun 29

    Anonymous says:

    Hi, It looks like the "LDAP Browser" link is broken.

    Hi, It looks like the "LDAP Browser" link is broken.

    1. Jun 29

      Timothy Chin says:

      I believe that the link has been moved to here: http://www.anl.gov/techtransfer/...

      I believe that the link has been moved to here: http://www.anl.gov/techtransfer/Software_Shop/LDAP/LDAP.html

      But then again, there are many other LDAP browsers out there: http://www.google.com.my/search?q=ldap+browser

      Cheers,
      Tim

    2. Jun 29

      Andrew Lui [Atlassian Technical Writer] says:

      Hi, Thanks for your comment. I have updated the document accordingly. Kind Reg...

      Hi,

      Thanks for your comment. I have updated the document accordingly.

      Kind Regards,
      Andrew

Add Comment


Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.