oauth-rest-atlassian

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.

npm install oauth-rest-atlassian

Config.json

Setup config.json at the root of the package.

{
    "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:

$ openssl genrsa -out rsa-key.pem 1024
$ openssl rsa -in rsa-key.pem -pubout -out rsa-key.pub

Setup application link

An application link 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:

$ openssl genrsa -out rsa-key.pem 1024

To obtain a certificate a certificate signing request must be generated:

$ 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:

$ openssl x509 -req -in certreq.csr -signkey rsa-key.pem -out rsa-cert.pem

Usage

Authorisation dance

Start the local website.

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
If your config is set to host at https://localhost then Bamboo authorisation - 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
If your config is set to host at https://localhost then get all plans from Bamboo - 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.

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.

Dependencies

oauth-rest-atlassian@0.4.24 - "MIT License (MIT)", documented by npm-licenses.

oauth-rest-atlassian

oauth-rest-atlassian

Installation

Config.json

OAuth private and public keys

Setup application link

SSL Private key and certificate

Usage

Authorisation dance

Using the REST API

API

Modules

rest

Changelog

License

Dependencies

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Last publish

Collaborators

oauth-rest-atlassian

oauth-rest-atlassian

Installation

Config.json

OAuth private and public keys

Setup application link

SSL Private key and certificate

Usage

Authorisation dance

Using the REST API

API

Modules

rest

Changelog

License

Dependencies

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads