# oauth-rest-atlassian [![view on npm](http://img.shields.io/npm/v/oauth-rest-atlassian.svg?style=flat)](https://www.npmjs.org/package/oauth-rest-atlassian) [![npm module downloads per month](http://img.shields.io/npm/dm/oauth-rest-atlassian.svg?style=flat)](https://www.npmjs.org/package/oauth-rest-atlassian) [![Dependency status](https://david-dm.org/Cellarise/oauth-rest-atlassian.svg?style=flat)](https://david-dm.org/Cellarise/oauth-rest-atlassian) [![Build Status](https://travis-ci.org/Cellarise/oauth-rest-atlassian.svg?branch=master)](https://travis-ci.org/Cellarise/oauth-rest-atlassian) [![Code Climate](https://codeclimate.com/github/Cellarise/oauth-rest-atlassian/badges/gpa.svg)](https://codeclimate.com/github/Cellarise/oauth-rest-atlassian) [![Test Coverage](https://codeclimate.com/github/Cellarise/oauth-rest-atlassian/badges/coverage.svg)](https://codeclimate.com/github/Cellarise/oauth-rest-atlassian/badges/coverage.svg) > An OAuth wrapper to authenticate and use the Atlassian REST API. The initial authorisation dance is managed through a local web page. ## Installation Install as a local package. ```cmd npm install oauth-rest-atlassian ``` ### Config.json Setup config.json at the root of the package. ```js { "protocol": "http", "host": "localhost", "port": "8080", "SSLPrivateKey": "", "SSLCertificate": "", "consumerPrivateKeyFile": "rsa.pem", "applications": { "jira": { "protocol": "https", "host": "myhost.com", "port": "443", "oauth": { "consumer_key": "node-oauth-key1", "consumer_secret": "", "access_token": "", "access_token_secret": "" }, "paths": { "request-token": "/plugins/servlet/oauth/request-token", "access-token": "/plugins/servlet/oauth/access-token", "authorize": "/plugins/servlet/oauth/authorize" } }, "bamboo": { "protocol": "https", "host": "myhost.com", "port": "443", "oauth": { "consumer_key": "node-oauth-key1", "consumer_secret": "", "access_token": "", "access_token_secret": "" }, "paths": { "request-token": "/plugins/servlet/oauth/request-token", "access-token": "/plugins/servlet/oauth/access-token", "authorize": "/plugins/servlet/oauth/authorize" } } } } ``` ### OAuth private and public keys A private-public key pair is required to establish OAuth authorisation with an Atlassian product. The private key and public key can be generated using openssl: ```cmd $ openssl genrsa -out rsa-key.pem 1024 $ openssl rsa -in rsa-key.pem -pubout -out rsa-key.pub ``` ### Setup application link An [application link](http://confluence.atlassian.com/display/JIRA/Configuring+Application+Links) profile must be established on the Atlassian product using a public key. The Application Link requests the URL of the application to link. This URL is not used and a fill value should be used like `http://rest`. In the create link screen (you can enter an application name of your choice): * Application name: `Node OAuth` * Application type: `Generic Application` * Create incoming link: check In the incoming link screen (you can enter an application name of your choice): * Consumer Key: `node-oauth-key1` * Consumer Name: `Node OAuth` * Public Key: copy public key contents excluding the header `-----BEGIN PUBLIC KEY-----` and footer `-----END PUBLIC KEY-----`. ### SSL Private key and certificate To run the local website using the https protocol you will need an SSL private key and certificate. The private key can be generated using openssl: ```cmd $ openssl genrsa -out rsa-key.pem 1024 ``` To obtain a certificate a certificate signing request must be generated: ```cmd $ openssl req -new -key rsa-key.pem -out certreq.csr $ openssl x509 -req -in certreq.csr -signkey rsa-key.pem -out rsa-cert.pem ``` The certificate signing request should be sent to a certificate authority for to perform the certificate signing process. However, for internal development purposes a self signed certificate can be generated: ```cmd $ openssl x509 -req -in certreq.csr -signkey rsa-key.pem -out rsa-cert.pem ``` ## Usage ### Authorisation dance Start the local website. ```cmd npm start ``` Open the website at path /jira for JIRA authorisation or /bamboo for Bamboo authorisation: * If your config is set to host at `https://localhost` then JIRA authorisation - [https://localhost/jira](https://localhost/jira) * If your config is set to host at `https://localhost` then Bamboo authorisation - [https://localhost/bamboo](https://localhost/bamboo) If you have configured the https protocol and used a self signed certificate you will need to navigate security warnings. If the Atlassian application configuration is valid and you have setup the application link correctly you should see the authorisation page. Click the Allow button to retrieve and save the OAuth access tokens. You can now use the REST API for the Atlassian product. ### Using the REST API You can test the REST API using the local website and path `/rest?req=`. For example: * If your config is set to host at `https://localhost` then get all projects from JIRA - [https://localhost/jira/rest?req=project](https://localhost/jira/rest?req=project) * If your config is set to host at `https://localhost` then get all plans from Bamboo - [https://localhost/bamboo/rest?req=plan](https://localhost/bamboo/rest?req=plan) ## API ### Modules
utils/config ⇒ Object

Application configuration utility

rest

Execute a rest query using the http GET, POST, PUT or DELETE method

### utils/config ⇒ Object Application configuration utility **Returns**: Object - configuration for application | Param | Type | Description | | --- | --- | --- | | application | String | application | - ### rest Execute a rest query using the http GET, POST, PUT or DELETE method | Param | Type | Default | Description | | --- | --- | --- | --- | | opts | Object | | required options | | [opts.config] | Object | | the configuration object which must contain the following properties: config.protocol - the protocol of the JIRA server (http/https) config.host - the host address of the JIRA server config.port - the port of the JIRA server config.paths["request-token"] - the oauth request-token config.paths["access-token"] - the oauth access-token config.oauth.consumer_key - the oauth consumer key config.oauth.consumer_secret - the oauth consumer secret | | [opts.query] | Object | | the rest query url | | [opts.method] | Object | "get" | optional the http method - one of get, post, put, delete | | [opts.postData] | Object | "" | optional the post data for create or update queries. | | cb | function | | the callback function called once the search has completed. The callback function must have the following signature: done(error, data). - error - an error object returned by oauth - data - the data returned as a JSON object | - *documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown)*. # Changelog
Type ID Summary
Version: 0.4.25 - released 2017-01-02
Non-functional MDOAUTH-48

Oauth: Set querystring.parse return object to prototypically extend from the JavaScript Object
Version: 0.4.24 - released 2016-06-18
Non-functional MDOAUTH-47

Package: Update package dependencies
Version: 0.4.23 - released 2016-02-16
Non-functional MDOAUTH-46

Package: Update package dependencies
Version: 0.4.22 - released 2015-10-05
Usability MDOAUTH-45

Package: Fix invalid config JSON in README
Version: 0.4.21 - released 2015-09-28
Usability MDOAUTH-44

Package: Fix invalid config JSON in README
Version: 0.4.20 - released 2015-08-25
Non-functional MDOAUTH-42

Package: Update development dependencies and configure for travis-ci
Minor MDOAUTH-43

OAuth: Refactor use of config.json and add default config
Version: 0.4.19 - released 2015-08-04
Non-functional MDOAUTH-41

Package: Update package dependencies
Version: 0.4.18 - released 2015-08-02
Non-functional MDOAUTH-40

Package: Update package dependencies
Version: 0.4.17 - released 2015-07-07
Non-functional MDOAUTH-39

Package: Update package dependencies
Version: 0.4.16 - released 2015-06-22
Non-functional MDOAUTH-38

Package: Update package dependencies
Version: 0.4.15 - released 2015-05-24
Non-functional MDOAUTH-37

Package: Update development dependencies
Version: 0.4.14 - released 2015-05-21
Non-functional MDOAUTH-36

Package: Update jsdoc2markdown and regenerate documentation
Version: 0.4.13 - released 2015-04-20
Non-functional MDOAUTH-33

Package: Update package dependencies
Non-functional MDOAUTH-35

Package: Update package dependencies
Non-functional MDOAUTH-34

Package: Update package dependencies
Version: 0.4.12 - released 2015-02-24
Non-functional MDOAUTH-32

Package: Update package dependencies
Non-functional MDOAUTH-31

Package: Update eslint configuration, test.js runner and dev dependencies
Version: 0.4.11 - released 2015-02-03
Non-functional MDOAUTH-30

Package: Update package dependencies
Version: 0.4.10 - released 2015-01-22
Non-functional MDOAUTH-29

Package: Update package dependencies
Version: 0.4.9 - released 2015-01-15
Non-functional MDOAUTH-28

Package: Update package dependencies
Version: 0.4.8 - released 2015-01-07
Non-functional MDOAUTH-26

Package: Update package dependencies
Non-functional MDOAUTH-23

Package: Update package dependencies
Non-functional MDOAUTH-27

Package: Update eslint configuration, test.js runner and dev dependencies
Non-functional MDOAUTH-25

Package: Update package dependencies
Non-functional MDOAUTH-24

Package: Update package dependencies
Version: 0.4.7 - released 2014-11-25
Non-functional MDOAUTH-22

Package: Update package dependencies
Version: 0.4.6 - released 2014-11-11
Non-functional MDOAUTH-21

Package: Update package dependencies
Version: 0.4.5 - released 2014-11-07
Non-functional MDOAUTH-20

Package: Update package dependencies
Version: 0.4.4 - released 2014-10-20
Non-functional MDOAUTH-19

Package: Update package dependencies
Non-functional MDOAUTH-18

Package: Migrate from jshint to eslint static code analysis
Version: 0.4.3 - released 2014-10-17
Non-functional MDOAUTH-17

Package: Update package dependencies
Non-functional MDOAUTH-16

Package: Remove all gulp tasks except 'test' and update readme docs
Non-functional MDOAUTH-15

Tests: Update config.json environment variable provided by CI server
Version: 0.4.2 - released 2014-09-14
Bug MDOAUTH-14

Rest: Fix object parse error when receiving an empty response from a post
Version: 0.4.1 - released 2014-09-13
Non-functional MDOAUTH-13

Package: Update test.js to enable relative library annotations in test features

Version: 0.4.0 - released 2014-09-13
Feature MDOAUTH-12

Rest: Add Atlassian Bamboo support

As a developer I can execute a Bamboo rest query using oauth config So that I can efficiently read data or write data to my Bamboo server
Version: 0.3.0 - released 2014-09-09
Feature MDOAUTH-11

Rest: Add post, put and delete methods to rest function

As a developer I can execute a JIRA rest query using the post, put and delete methods So that I can efficiently create, update or delete data on my JIRA server
Version: 0.2.2 - released 2014-09-06
Non-functional MDOAUTH-10

Readme: Fix error in changelog.
Version: 0.2.1 - released 2014-09-06
Bug MDOAUTH-9

Rest: Fix function hang when provided invalid options.
Version: 0.2.0 - released 2014-09-05
Feature MDOAUTH-7

Package: Add Atlassian JIRA rest query function

As a developer I can execute a JIRA rest query using oauth config So that I can efficiently read data or write data to my JIRA server
Version: 0.1.1 - released 2014-09-02
Non-functional MDOAUTH-6

Web server: Fix mistakes in the readme describing how to launch the server and the private key entry step.
Version: 0.1.0 - released 2014-09-02
Feature MDOAUTH-4

OAuth: OAuth authorisation dance

As a developer I can authorise my OAuth REST connection using a private key So that I do not need to store my password
# License MIT License (MIT). All rights not explicitly granted in the license are reserved. Copyright (c) 2015 John Barry ## Dependencies [oauth-rest-atlassian@0.4.24]("https://github.com/Cellarise/OAuth-REST-Atlassian") - "MIT License (MIT)", *documented by [npm-licenses](http://github.com/AceMetrix/npm-license.git)*.