How to build a public Jira Software Server integration: Building the Auth Flow

Aug 3, 2024 • 6 minute read

Hey there, fellow JavaScript enthusiast! Ready to dive into the world of Jira Software Server integrations? Today, we're going to focus on one of the most crucial aspects of building a public integration: the authorization flow. Buckle up, because we're about to make your integration secure and user-friendly!

Prerequisites

Before we jump in, make sure you've got:

A Jira Software Server instance up and running
Node.js installed on your machine
A solid grasp of OAuth 1.0a (don't worry, we'll refresh your memory as we go)

Setting up the project

Let's kick things off by setting up our project:

mkdir jira-integration
cd jira-integration
npm init -y
npm install oauth express

Great! Now we've got our basic structure and dependencies in place.

Implementing OAuth 1.0a flow

Request temporary token

First things first, we need to get a temporary token from Jira. Here's how:

const OAuth = require('oauth').OAuth;

const oauth = new OAuth(
  'https://your-jira-instance.com/plugins/servlet/oauth/request-token',
  'https://your-jira-instance.com/plugins/servlet/oauth/access-token',
  'your-consumer-key',
  'your-consumer-secret',
  '1.0',
  'http://localhost:3000/callback',
  'RSA-SHA1'
);

app.get('/auth', (req, res) => {
  oauth.getOAuthRequestToken((error, token, tokenSecret, results) => {
    if (error) {
      console.error('Error getting OAuth request token : ' + error);
      res.send('OAuth failed');
    } else {
      req.session.oauth = { token, tokenSecret };
      res.redirect(`https://your-jira-instance.com/plugins/servlet/oauth/authorize?oauth_token=${token}`);
    }
  });
});

User authorization

Now, we'll redirect the user to Jira's authorization page. Once they approve, Jira will send them back to our callback URL.

Exchanging for access token

Time to exchange that temporary token for an access token:

app.get('/callback', (req, res) => {
  const { oauth_token, oauth_verifier } = req.query;
  const { token, tokenSecret } = req.session.oauth;

  oauth.getOAuthAccessToken(
    token,
    tokenSecret,
    oauth_verifier,
    (error, accessToken, accessTokenSecret, results) => {
      if (error) {
        console.error('Error getting OAuth access token : ' + error);
        res.send('OAuth failed');
      } else {
        // Store these securely!
        req.session.accessToken = accessToken;
        req.session.accessTokenSecret = accessTokenSecret;
        res.redirect('/dashboard');
      }
    }
  );
});

Creating authenticated requests

Now that we've got our access token, let's use it to make an API call:

app.get('/user-info', (req, res) => {
  const { accessToken, accessTokenSecret } = req.session;

  oauth.get(
    'https://your-jira-instance.com/rest/api/2/myself',
    accessToken,
    accessTokenSecret,
    (error, data, response) => {
      if (error) {
        console.error('Error fetching user info: ' + error);
        res.status(500).send('Error fetching user info');
      } else {
        res.json(JSON.parse(data));
      }
    }
  );
});

Error handling and edge cases

Remember to handle token expiration and implement a refresh mechanism if Jira supports it. Always be prepared for API errors and handle them gracefully.

Security considerations

Security is paramount! Always use HTTPS, securely store tokens, and implement the state parameter to prevent CSRF attacks. Your users will thank you for keeping their data safe!

Testing the auth flow

Don't forget to thoroughly test your auth flow. Try manual testing by going through the flow yourself, and consider setting up automated tests using tools like Jest or Mocha.

Conclusion

And there you have it! You've just built a robust auth flow for your Jira Software Server integration. Pat yourself on the back – you're well on your way to creating an awesome, secure integration.

Additional resources

Want to dive deeper? Check out these resources:

Remember, the key to a great integration is attention to detail and a focus on user experience. Keep iterating, keep learning, and most importantly, keep coding! You've got this! 🚀