Documentation for JIRA 6.3 EAP developer (EAP) releases only. Not using this? See below:
(JIRA 6.2.x documentation | JIRA OnDemand documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata
Icon

This article applies to JIRA versions 4.3 and below. For all other versions, please refer to Configuring JIRA's SMTP Mail Server to Send Notifications

This page describes how to use a Gmail account as either an SMTP mail server to send notifications from JIRA or a POP3 mail server to receive email messages that create JIRA issues or comments, or both.

Configuring JIRA to use Gmail as an SMTP mail server

  1. Shut down JIRA.
  2. Move (not copy) the 'activation' and 'mail' JAR files from the from the <jira-application-dir>/WEB-INF/lib/ subdirectory of the JIRA Installation Directory to the /common/lib (Tomcat 5.5) or /lib (Tomcat 6) subdirectory of the JIRA Installation Directory (for 'recommended' distributions of JIRA) or the lib/ subdirectory of the application server running JIRA.
    For example, on a *nix-based system, at a shell prompt, change directory into the JIRA Installation Directory (of a 'recommended' distribution of JIRA) and enter the following:

  3. Add Gmail as a JNDI resource within the within the <Context/> elements of the /conf/server.xml file. Change your username and password to those required to authenticate against your Gmail account:

  4. If you are not using the built in cacerts file, you will need to add Gmail as a secure server. (Most default configurations can skip this step).

     Click here to expand...
    1. Download OpenSSL:
    2. Import the SSL certificate from Gmail:

      • For Windows: double-click the openssl file from the directory that gets installed. Run

      • For Linux: run:

    3. From the output, you want only the alphanumeric string between the lines which say 'BEGIN CERTIFICATE' and 'END CERTIFICATE' (inclusive). Copy the results into a file called gmail.cert using your favorite text editor.           

    4. Exit the openssl prompt and return to your Java installation's bin directory. Import the cert into your keystore:

      • For Windows:

        (tick) Tip:

        • "A keystore is created whenever you use a -genkey, -import, or -identitydb command to add data to a keystore that doesn't yet exist. More specifically, if you specify, in the -keystore option, a keystore that doesn't yet exist, that keystore will be created. If you don't specify a -keystore option, the default keystore is a file named .keystore in your home directory. If that file does not yet exist, it will be created."
          From Sun´s Documentation on Keytool

      • For Linux:

    (tick) Tip: The default keystore password is changeit

  5. Restart JIRA so that JIRA will acknowledge the JNDI location you defined above.

  6. Follow the instructions in Configuring JIRA's SMTP Mail Server to Send Notifications to configure JIRA's SMTP mail server and at the second part of the configuration, specify in the JNDI Location field (if using the default example above):

Configuring Gmail for Incoming Mail (POP)

To use Gmail, for example, as a create and comment mail handler:

If you did not import the SSL certificate from Gmail during configuration of Gmail as an SMTP mail server, refer to the instructions above.

Enable POP access in your Gmail account's settings.

Add a POP3 mail account in JIRA.

30 Comments

  1. Here's what I did for Step 1 of Incoming Mail (our outgoing mail wasn't using gmail) with standard JIRA standalone and Tomcat.

    1. Move the mail, activation jars to common/lib from atlassian-jira/WEB-INF/lib
    2. openssl s_client -connect pop.gmail.com:995 > /tmp/gmail.cert and then edit the gmail.cert file to remove everything except the BEGIN and END and the lines between. Expect some errors in the download.
    3. keytool -import -alias jiramailserver -keystore /usr/local/jira/keystore -file /tmp/gmail.cert Note that the password has to be changeit if you're creating a new keystore
    4. Add JAVA_OPTS="-Djavax.net.ssl.trustStore=/usr/local/jira/keystore $JAVA_OPTS" to the top of bin/setenv.sh

    but I have to say, the documentation for this task is rather scattered across Configuring+JIRA+to+Send+SMTP+Mail, Connecting+to+SSL+services and elsewhere. This blog post was helpful too.

    1. keystore is a file.
      Enable IMAP in gmail.
      Don't forget to use SSL in the IMAP Service configuration

  2. AFAIK This actually cannot work because of this bug w/no workaround

      http://jira.atlassian.com/browse/JRA-17031

    Essentially, you have to use JNDI to configure SMTP server and Mail handlers cannot read SMTP server from JNDI

  3. Douglas, can you be more specific? Outgoing mail is working for me.

  4. Hi,

    I've followed this explanation to the letter but bumped in to following keytool error.

    Does anybody have an idea?

    Thanks!!

    (OSX server 10.6)

    1. Anonymous

      I've run into exactly the same problem, running mac OSX 10.6.4. The error:keytool error: java.lang.Exception: Input not an X.509 certificate

      Does anyone have a view on how to resolve this?

      Many thanks

    2. Anonymous

      Make sure you include the "BEGIN CERTIFICATE" and "END CERTIFICATE" lines in the cert.

    3. Maarten,

             I ran into the same issue, a little bit of digging around revealed that the gmail.cert is not in the correct format. The X.509 error can happen if you improperly copy the characters (i.e get something else other than the stuff between BEGIN and END) ... but in our case it was due to the format.

      Here are the steps that worked for me:

      * run the command 'openssl s_client -connect smtp.gmail.com:465'

      * copy the characters from gmail to a file called gmail.pem

      * run the command 'openssl.exe x509 -outform der  -in gmail.pem -out gmail.der'

      * check your folder you should see a b64 certificate

      * use this in the keytool import as mentioned here

      cheers!

    4. Anonymous

      Hi Maarten,

      There could be a format error in the gmail.cert that you wish to import.  For example, you'll see this Exception when the BEGIN and END lines have been removed.  Another possibility is that you downloaded the cert into a different format, such as PKCS #7.

    5. This can be solved this by removing trailing spaces at the end of the key.

      - Abi

  5. For Windows users, if you already have Apache with OpenSSL installed (e.g. httpd-2.2.16-win32-x86-openssl-0.9.8o.msi) then an openssl binary is already included in the httpd/bin directory, and you can use the same command syntax as for Linux.

    Also, the import command line should use %JAVA_HOME%, not $JAVA_HOME:

  6. Anonymous

    I spent several hours working on this and finally got it to work.  After reviewing everything, the instructions are pretty accurate. The only thing I changed was that I didn't specify a -keystore location (used the default).  

    That said, I have to say that these instructions are terribly communicated.  Things need to be more specific and just better communicated in general.  It's too ambiguous and unclear the way it's currently written.  I spent way too much time configuring JIRA for windows.  

  7. Can someone please tell me where I can find the activation and mail jar files they are telling us to move on a Windows machine... 

  8. I am trying to set up Gmail as our POP service so we can create Issues/Comments through email.

    I am trying to set up the SSL Certificate per the instructions above but keep getting a "keytool error: java.io.FileNotFoundException" ... which doesn't make sense to me because I have verified both files are there and am using the JIRA~ notation because our folder is JIRA 4.1.2

    The other side of this is ... we already have Gmail set up as our SMTP server but didn't have to do ANYTHING special for that to work, despite the instructions above saying that is needed ... do I even need to set up the SSL certificate for POP, if we don't have it going for the SMTP server which is working fine?

    1. So ... I got the SSL certificate imported (I needed to use the DOS safe folder paths) ...

      But it still isn't working ... when SSL is on in the service, nothing shows in the logs at all and no emails are imported .... when SSL is off, I get a "javax.mail.AuthenticationFailedException: EOF on socket" error ...

      Can anyone help, please? I also started a thread in the forums but haven't gotten any help yet.

      Thanks!

      1. Anonymous

        "(I needed to use the DOS safe folder paths) ..." What does this mean? Some examples?

        1. DOS safe means no spaces and a max length of 8 characters per folder.

          If you're in command prompt, you CD to the directory of the folder you want to know about and type in dir /x

          Here is my resource: http://forums.techarena.in/window-2000-help/740491.htm

  9. Anonymous

    For anyone else following this guide (and numerous others), yet still getting javax.net.ssl.SSLException: Unrecognized SSL message, plaintext connection?, see http://confluence.atlassian.com/display/JIRAKB/Sending+Email+through+an+SMTP+Server+via+SSL+Fails+due+to+Resource+Configuration. Apparently you need to not add mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory".

  10. Anonymous

    Hello,

    I don't underdtand how to Add Gmail as a JNDI Resource in /conf/server.xml in-between

    JIRA's <Context>...</Context> and what is exactly de jar file (exact name) and where is de tomcat

    folder in jira 4.2 standalone where the jar files go.

    thanks

    Marc

  11. Hopefully this will be useful to others, since it took me a while to figure it out. When I pasted the JNDI name 'java:comp/env/mail/GmailSmtpServer' into the administration screen a trailing space was included, which caused a javax.naming.NameNotFoundException to be thrown.

    It would be nice if both the input box in the form were wider and if the code trimmed any leading or trailing whitespace.

    1. Anonymous

      Darn I'm getting this error too but I don't have any leading or trailing spaces. Has

      anyone else solved this error in a different way? 

  12. I am using Windows Server the command

    keytool -import -alias smtp.gmail.com -keystore $JAVA_HOME/jre/lib/security/cacerts -file C:\path\to\gmail.cert

    did not work on me instead i just specify the windows path and it work well.

    command:

    keytool -import -alias smtp.gmail.com -keystore "C:\Program Files\Java\jre6\lib\security\cacerts" -file C:\gmail.cert

  13. Anonymous

    Is there any reason why Atlassian suggests against using the system provided CACerts file, which would negate the need to import every certificate?

    1. You're right! I've updated the instructions - gmail works out of the box with a default cacerts file.

  14. Man, I wish the errors when the mail server config is wrong were clearer.

  15. how can messages be SEAMLESSLY encryped?  SSL/TLS alone is woefully deficient

     

    1. Just noticed this, not sure I specifically understand.  SSL is pretty standard as a transport security.

      If you mean, how can messages be encrypted from a user desktop and remain entirely encrypted in transit until decryption at JIRA, then no, JIRA doesnt do that out of the box.  SSL, which is the topic of woe for most comments, guarantees transport security between GMAIL and JIRA, so it doesnt matter if the email isn't encrypted.  Back to the first point:  If you just wanted to ensure integrity and non-repudiation of the message (that nobody changed it and that it came from who you think it came from) then Email Signing is pretty doable.  Email Encryption is a variation on the them.

      JEMH 1.0 starts to support GPG email signing as a first step in supporting encryption, if anyone has specific desires for supporting encryption, please vote on https://studio.plugins.atlassian.com/browse/JEMH-551

  16. The functionality for Gmail as SMTP is provided out of the box in JIRA 5 (well, I have 5.1.3) from administration web interface

  17. Hi,

    I keep getting the same error.

    Unfortunately no connection was possible. Review the errors below and rectify:

    • ConnectException: Connection refused: connect

    Any idea why I am getting that?

    Thanks,

    Melvin