atlassian-crowd-client

Promise-based client library to communicate with an Atlassian Crowd server from Node, written in ES6. This uses the Crowd REST APIs.

Installation

npm install --save atlassian-crowd-client

Usage

var CrowdClient = require('atlassian-crowd-client');
var User = require('atlassian-crowd-client/lib/models/user');

// Initialize the Crowd client:
var crowd = new CrowdClient({
  baseUrl: 'https://crowd.example.com/',
  application: {
    name: 'demo',
    password: 'example'
  }
});

// Create a new user:
crowd.user.create(new User('John', 'Doe', 'John Doe', 'johndoe@example.com', 'johndoe', 'secret'));

// Authenticate to Crowd:
crowd.session.create('someusername', 'somepassword').then(function (session) {

  // Fetch the user profile:
  crowd.session.getUser(session.token).then(function (user) {
    console.log('Hello, ' + user.displayname);
  });
});

// Find all active groups (using Crowd Query Language):
crowd.search.group('active=true').then(function (groups) {
  console.log('Found groups: ' + groups.length);
});

Configuration

Refer to the example settings file for all configurable options.

API

The package provides two main classes: CrowdApi and CrowdClient.

The CrowdApi class implements a generic interface to make HTTP requests to the Crowd REST API. It ensures that the appropriate headers are used and errors are handled. It also wraps the callbacks in promises.

The CrowdClient class makes all Crowd REST Resources and their variants/options available as convenient JavaScript methods. Each method provides sensible defaults and maps responses to common domain objects.

Domain model objects

In order to provide a consistent API, most CrowdClient methods map Crowd API responses to domain objects. Many parameters are also expected to be a domain object. Here's an overview of the domain models and their properties:

Session

token (string): Session token as generated by Crowd.
createdAt (Date): Creation date/time of the session token.
expiresAt (Date): Expiration date/time of the session token.

Group

groupname (string): Name of the group.
description (string): Description for the group.
active (boolean): Whether the group is active or not.

User

firstname (string): First name.
lastname (string): Last name.
displayname (string): Display name (i.e. full name).
email (string): Email address.
username (string): Username (i.e. login name).
password (string): Password, only used when creating a new user, never returned by Crowd.
active (boolean): Whether the user is active or not.

Attributes

attributes (object): User/Group attributes as key-value pairs.

ValidationFactors

validationFactors (object): Validation factors as key-value pairs.

Development

The library is completely written in ES6, using babel-node to run tests. Source code is compiled to ES5 before publication to NPM, so the library can also be used in ES5 projects.

Included are integration tests to verify proper functioning of all endpoints. For this you will need to provide settings for a Crowd test server, since the integration tests will make actual HTTP requests. An example settings file is provided at test/helpers/settings-example.js. Copy or rename it to settings.js and provide your own configuration.

git clone https://github.com/wehkamp/atlassian-crowd-client.git
cd atlassian-crowd-client
cp test/helpers/settings-example.js test/helpers/settings.js
npm install
npm test

ghengeveld/atlassian-crowd-client